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,
    profiles_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 span and recorder type. Samples include traces and errors. Default value is 5.
  • profiles_per_min: Maximum number of profiles per minute to be recorded per span and recorder type. To disable profiling, set to 0. Default value is 1.
  • 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 profiles_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.remove_attribute

remove_attribute(name: str) -> None

Remove a process-level attribute.

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