Python Tracer API

graphsignal.configure

configure(
    api_key: Optional[str] = None, 
    api_url: Optional[str] = None, 
    deployment: Optional[str] = None, 
    tags: Optional[dict[str, str]] = None,
    auto_instrument: Optional[bool] = True,
    record_payloads: Optional[bool] = True,
    upload_on_shutdown:  Optional[bool] = True,
    debug_mode: Optional[bool] = False) -> None

Configures and initializes the Graphsignal tracer.

All arguments can also be passed via environment variables: GRAPHSIGNAL_{ARG_NAME_UPPERCASE}. To pass tags as an environment variable, use the format k1=v1,k2=v2. Arguments passed directly to the function take precedence.

Arguments:

  • api_key: The access key for communication with Graphsignal cloud.
  • api_url: Graphsignal on-premise server URL. Defaults to Graphsignal cloud.
  • deployment: A unique name to group and identify operations for a particular deployment, version or environment.
  • tags: Run-level tags to group and filter recorded data.
  • auto_instrument: Enable/disable automatic instrumentation of libraries and frameworks.
  • record_payloads: Enable/disable recording of data samples along with data statistics.
  • upload_on_shutdown: Enable/disable uploading of outstanding metrics on process or tracer shutdown.
  • debug_mode: Enable/disable debug logging.

Raises:

  • ValueError - When arguments are missing or invalid.

graphsignal.set_tag

set_tag(key: str, value: Any) -> None

Set run-level tags to group and filter recorded data.

To remove a tag, set its value to None.

Arguments:

  • key: Tag key.
  • value: Tag value. Will be converted to string using str().

graphsignal.set_context_tag

set_context_tag(key: str, value: Any) -> None

Set context-level tags to group and filter recorded data. Context tags are propagated to all operation in the same context, e.g. a web application request. Run-level tags with same keys will be overwritten.

To remove a tag, set its value to None.

Arguments:

  • key: Tag key.
  • value: Tag value. Will be converted to string using str().

graphsignal.trace

trace(
    operation: str,
    tags: Optional[dict[str, str]] = None) -> Span

Measure and trace operation.

with context manager can be used around the function call or code segment. Otherwise, stop() method should be called on the returned Span object.

Arguments:

  • operation: Unique identifier for a function or code segment.
  • tags: Trace-level tags to group and filter recorded data. Run-level and context-level tags with same keys will be overwritten.

Returns:

  • Span - span object representing currently active operation, e.g. inference.

graphsignal.trace_function

trace_function(
    operation: Optional[str],
    tags: Optional[dict[str, str]] = None)

A decorator for measuring and tracing function operation. If operation is not set, function name will be set as operation name.

@graphsignal.trace_function
def predict(x):
    return model(x)

You can set operation name and also provide tags, which will be added to each recorded operation.

@graphsignal.trace_function(operation='predict', tags=dict(t1=1))
def predict(x):
    return model(x)

Arguments:

  • operation: Unique identifier for a function or code segment.
  • tags: Trace-level tags to group and filter recorded data. Run-level and context-level tags with same keys will be overwritten.

graphsignal.current_span

current_span() -> Optional[Span]

Returns current span or None. Useful for adding information to the Span in the current context, e.g. user request.

Returns:

  • Span - span object representing currently active operation, e.g. inference.

graphsignal.score

score(
    name: str, 
    tags: Optional[dict[str, str]], 
    score: Optional[Union[int, float]] = None, 
    severity: Optional[int] = None, 
    comment: Optional[str] = None) -> None

Create a score associated with the tags.

Arguments:

  • name: Score name.
  • tags: Tags to associate the score with, e.g. run_id, session_id, or user_id.
  • score: Score value.
  • severity: Score severity from 1 to 5, corresponding to: 1 - critical, 2 - high, 3 - medium, 4 - low, 5 - informational.
  • comment: Any comment or description for the score.

graphsignal.upload

upload(block: Optional[bool] = False) -> None

Performance data is uploaded periodically. Call this method to initiate upload.

Arguments:

  • block: If set to true True, any outstanding data will be uploaded in the current thread instead of a new thread.

graphsignal.shutdown

shutdown() -> None

Clean up and shut down the tracer.

Normally, when python scripts exists, this method is automatically called. Use this method, if you want to explicitly clean up and shut down the tracer.

graphsignal.Span

Span object represent currently active operation. It is returned by graphsignal.trace() method and should not be created directly.

graphsignal.Span.is_sampling

is_sampling() -> bool

Returns True if current operation is being recorded.

graphsignal.Span.set_tag

set_tag(key: str, value: Any) -> None

Set operation-level tags to group and filter recorded data. Run-level and context-level tags with same keys will be overwritten.

To remove a tag, set its value to None.

Arguments:

  • key: Tag key.
  • value: Tag value. Will be converted to string using str().

graphsignal.Span.add_exception

add_exception(exc: Optional[Exception] = None, exc_info: Optional[bool] = None) -> None

When with context manager is used with graphsignal.trace() method, exceptions are automatically reported. For other cases, use this method.

Arguments:

  • exc: Exception object.
  • exc_info: When True, the sys.exc_info() will be called internally.

graphsignal.Span.set_payload

set_payload(
    name: str, 
    content: Any, 
    usage: Optional[dict[str, Union[int, float]]] = None, 
    record_payload: Optional[bool] = True) -> None

Measure any data related to current operation, e.g. input, output, to track data metrics and record data profiles and samples that will be available within traces.

with graphsignal.trace('generate') as span:
    span.set_payload('input', input_data, usage=dict(token_count=input_token_count))

To append to data, use graphsignal.Span.append_payload with same parameters instead. content must support the + operator.

Arguments:

  • name: Payload name, e.g. 'input'
  • content: Payload object. The following types are currently supported: list, dict, set, tuple, str, bytes.
  • usage Set additional usage counts, e.g. token_count.
  • record_payload: Enable/disable recording of a data payload, e.g. prompt, along with data statistics.

graphsignal.Span.set_usage

set_usage(name: str, value: Union[int, float]) -> None

Set usage parameters, e.g. 'cost'

Arguments:

  • name: Usage counter name.
  • value: Usage counter value.

graphsignal.Span.score

score(
    name: str, 
    score: Optional[Union[int, float]] = None, 
    severity: Optional[int] = None, 
    comment: Optional[str] = None) -> None

Create a score associated with the span.

Arguments:

  • name: Score name.
  • score: Score value.
  • severity: Score severity from 1 to 5, corresponding to: 1 - critical, 2 - high, 3 - medium, 4 - low, 5 - informational.
  • comment: Any comment or description for the score.

graphsignal.Span.stop

stop() -> None

Stops measuring and tracing current operation, if tracing is active. This method is automatically called if with context manager is used around the code.