Python Tracer 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,
    samples_per_min: Optional[int] = None,
    include_profiles: Optional[list] = None,
    debug_mode: Optional[bool] = None

Configures and initializes the Graphsignal tracer.

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.
  • samples_per_min: Maximum number of samples per minute to be recorded per recorder type. Samples include profiles or traces. Default value is 10.
  • include_profiles: Profiles to be recorded for this process. If not provided, all supported profiles are recorded. When empty ([]), no profiles are recorded. Supported profiles are profile.cpython, profile.pytorch. Profiling is subject to sampling according to samples_per_min.
  • 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().
  • 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_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 and profiled spans in the same context, e.g. a web application request. Process tags with 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.
  • value: Tag value. Will be converted to string using str().

graphsignal.set_param

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

Record process-level parameter.

To remove a parameter, set its value to None or use remove_param().

Arguments:

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

graphsignal.remove_param

remove_param(name: str) -> None

Remove a process-level tag.

graphsignal.trace

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

Measure and record a 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.
  • include_profiles: Profiles to be recorded for this span. If not provided, all supported profiles are recorded. When empty ([]), no profiles are recorded. Supported profiles are profile.cpython, profile.pytorch. Profiling is subject to sampling according to samples_per_min.

Returns:

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

graphsignal.trace_function

trace_function(
    span_name: Optional[str],
    tags: Optional[dict[str, str]] = None,
    include_profiles: Optional[list] = 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.
  • include_profiles: Profiles to be recorded for this span. If not provided, all supported profiles are recorded. When empty ([]), no profiles are recorded. Supported profiles are profile.cpython, profile.pytorch. Profiling is subject to sampling according to samples_per_min.

graphsignal.report_error

report_error(
    name: str, 
    tags: Optional[dict[str, str]] = None, 
    level: Optional[str] = None, 
    message: Optional[str] = None,
    exc_info: Optional[tuple] = None) -> None

Create an error.

Arguments:

  • name: Error name.
  • tags: Error tags, e.g. run_id. Process and context tags will be added automatically.
  • level: Error level, one of: 'debug', 'info', 'warning', 'error', 'critical'. Invalid levels will be rejected and logged as errors.
  • message: Error message. If not provided and exc_info is provided, will be automatically constructed from the exception.
  • exc_info: Exception info tuple (type, value, traceback). If provided, will automatically extract stack trace and optionally construct 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 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 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 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_param

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

Record span-level parameter.

To remove a parameter, set its value to None.

Arguments:

  • name: Parameter name.
  • value: Parameter 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.set_profile

set_profile(
    name: str, 
    format: str,
    content: str) -> None

Record profiles related to current span, e.g. CPU profile.

with graphsignal.trace('generate') as span:
    span.set_profile('chrome-trace', trace_data)

Arguments:

  • name: Profile name, e.g. 'cpu-profile'
  • format: Profile format supported by Graphsignal, e.g. event-averages.
  • content: Profile contents.

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.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.