Python SDK API

graphsignal.configure

configure(
    api_key: Optional[str] = None,
    api_url: Optional[str] = None,
    tags: Optional[Dict[str, str]] = None,
    auto_instrument: Optional[bool] = None,
    debug_mode: Optional[bool] = None
) -> None

Configures and initializes the Graphsignal SDK.

All arguments can also be passed via environment variables: GRAPHSIGNAL_{ARG_NAME_UPPERCASE}. To pass tags as environment variables, use the GRAPHSIGNAL_TAG_{TAG_NAME_UPPERCASE} format. 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.
  • tags: Process-level tags, e.g. deployment, app_version, ab_test_segment.
  • auto_instrument: Enable/disable automatic instrumentation of libraries and frameworks. Auto-instrumentation is enabled by default.
  • debug_mode: Enable/disable debug logging. Disabled by default.

Raises:

  • ValueError - When arguments are missing or invalid.

graphsignal.set_tag

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

Set process tags to group and filter recorded data.

To remove a tag, set its value to None or use remove_tag().

Arguments:

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

graphsignal.remove_tag

remove_tag(key: str) -> None

Remove a process tag.

graphsignal.set_context_tag

set_context_tag(key: str, value: Any, append_uuid: Optional[bool] = False) -> None

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

To remove a tag, set its value to None or use remove_context_tag().

Arguments:

  • key: Tag key.
  • value: Tag value. Will be converted to string using str().
  • append_uuid: When True, appends a UUID to the value, e.g. for provided value myval the resulting tag value will be myval-44955cc4fc1d.

graphsignal.remove_context_tag

remove_context_tag(key: str) -> None

Remove a context tag.

Arguments:

  • key: Tag key.

graphsignal.profile_function

profile_function(
    func: Callable,
    category: Optional[str] = None,
    event_name: Optional[str] = None) -> None

Register a function for profiling. Available in Python 3.12+.

Arguments:

  • func: The function to profile. Can be any callable function, including methods and async functions.
  • category: Function category.
  • event_name: Custom name for the profiled function in the profile output. If not provided, the function's __qualname__ or __name__ will be used.

graphsignal.profile_function_path

profile_function_path(
    path: str,
    category: Optional[str] = None,
    event_name: Optional[str] = None) -> None

Register a function for profiling by providing its import path (for example, 'myapp.module.fn_name'). The specified function will be resolved at runtime and profiled during traced spans.

Available in Python 3.12+.

Arguments:

  • path: Dot-separated import path to the function to profile. Must resolve to a callable.
  • category: Function category.
  • event_name: Custom name for the profiled function in the profile output. If not provided, the function's __qualname__ or __name__ will be used.

graphsignal.profile_cuda_kernel

profile_cuda_kernel(kernel_pattern: str, event_name: str) -> None

Register a CUDA kernel name pattern to be profiled. You can call this method multiple times with different patterns and the same event_name. Matching kernels are aggregated under that event_name.

This feature requires:

  • Linux (CUPTI is not supported on macOS)
  • CUDA + CUPTI available at runtime (e.g. libcupti.so loadable)

Arguments:

  • kernel_pattern: Case-insensitive substring to match against the kernel name reported by CUPTI (often a mangled C++ symbol or library kernel name).
  • event_name: Category/name shown in the profile output (for example matmul_gemm, attention_flash, nccl).

graphsignal.trace

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

Measure and record an execution span.

with context manager is supported. Otherwise, stop() method should be called on the returned Span object.

Arguments:

  • span_name: Traced span name.
  • tags: Trace tags. Process and context tags will be added automatically.

Returns:

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

graphsignal.trace_function

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

A decorator for tracing a function. If span_name is not set, function name will be used.

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

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

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

Arguments:

  • span_name: Traced span name.
  • tags: Trace tags. Process and context tags will be added automatically.

graphsignal.log_message

log_message(
    message: str, 
    tags: Optional[dict[str, str]] = None, 
    level: Optional[str] = None,
    exception: Optional[str] = None) -> None

Send a log message.

Arguments:

  • message: Log message text.
  • tags: Log tags, e.g. run_id. Process and context tags will be added automatically.
  • level: Log level, one of: 'debug', 'info', 'warning', 'error', 'critical'. Defaults to 'info' if not provided.
  • exception: Exception stack trace as a string. If provided, will be included with the log message.

graphsignal.tick

tick(block: Optional[bool] = False, force: Optional[bool] = False) -> None

Schedule generating and uploading telemetry data. This method is called automatically, it's only useful to call it in special cases.

Arguments:

  • block: If set to True, will block.
  • force: If True, will execute immediately. Otherwise, this method only executes at most once per internal interval.

graphsignal.shutdown

shutdown() -> None

Clean up and shut down the SDK.

Normally, when Python scripts exit, this method is automatically called. Use this method if you want to explicitly clean up and shut down the SDK.

graphsignal.Span

The Span object represents the currently active code span. It is returned by graphsignal.trace() method and should not be created directly.

graphsignal.Span.set_tag

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

Set span tags. Process and context tags will be added automatically.

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_attribute

set_attribute(name: str, value: Any) -> None

Record span attribute.

To remove an attribute, set its value to None.

Arguments:

  • name: Attribute name.
  • value: Attribute value. Will be converted to string using str().

graphsignal.Span.set_counter

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

Set any span measurement.

Arguments:

  • name: Counter name.
  • value: Counter value.

graphsignal.Span.inc_counter

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

Increment any span measurement.

Arguments:

  • name: Counter name.
  • value: Counter value.

graphsignal.Span.trace

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

Measure and record sub-spans.

with context manager is supported. Otherwise, stop() method should be called on the returned Span object.

Arguments:

  • span_name: Traced span name.
  • tags: Trace tags. Process and context tags will be added automatically.

Returns:

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

graphsignal.Span.inc_counter_metric

inc_counter_metric(name: str, value: Union[int, float], unit: Optional[str] = None) -> None

Set/increment global counter metric. All tags of this span will be applied to the metric. Useful for tracking usage.

Arguments:

  • name: Metric name.
  • value: Metric value.
  • unit: Metric unit.

graphsignal.Span.set_sampled

set_sampled(sampled: bool) -> None

Set whether the span should be sampled and recorded.

Arguments:

  • sampled: Whether the span should be sampled and recorded.

graphsignal.Span.is_sampled

is_sampled() -> bool

Check if the span is currently marked for sampling.

Returns:

  • bool - True if the span is sampled, False otherwise.

graphsignal.Span.stop

stop() -> None

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