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,
    sampling_rate: Optional[float] = None,
    profiling_rate: Optional[float] = 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.
  • sampling_rate: Fraction of operations to be recorded. Default value is 1.0, i.e. 100% of operations will be recorded.
  • profiling_rate: Fraction of operations to be profiled when tracing manually or automatically for auto-instrumented libraries, if applicable. To disable profiling, set to 0, to profile every operation, set to 1. Default value is 0.1, i.e. 10% of recorded operations will be profiled.
  • 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 python-time-profile, pytorch-cpu-profile, pytorch-kernel-profile, pytorch-timeline. Profiling is subject to sampling according to profiling_rate.
  • 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 operation 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(
    operation: str,
    tags: Optional[dict[str, str]] = None,
    include_profiles: Optional[list] = None) -> Span,

Measure and record an operation.

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

Arguments:

  • operation: Operation name.
  • tags: Trace tags. Process and context tags will be added automatically.
  • include_profiles: Profiles to be recorded for this operation. If not provided, all supported profiles are recorded. When empty ([]), no profiles are recorded. Supported profiles are python-time-profile, pytorch-cpu-profile, pytorch-kernel-profile, pytorch-timeline. Profiling is subject to sampling according to profiling_rate.

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,
    include_profiles: Optional[list] = None)

A decorator for 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: Operation name.
  • tags: Trace tags. Process and context tags will be added automatically.
  • include_profiles: Profiles to be recorded for this operation. If not provided, all supported profiles are recorded. When empty ([]), no profiles are recorded. Supported profiles are python-time-profile, pytorch-cpu-profile, pytorch-kernel-profile, pytorch-timeline. Profiling is subject to sampling according to profiling_rate.

graphsignal.report_issue

report_issue(
    name: str, 
    tags: Optional[dict[str, str]], 
    severity: Optional[int] = None, 
    description: Optional[str] = None,
    span: Optional[Span]) -> None

Create an issue.

Arguments:

  • name: Issue name.
  • tags: Issue tags, e.g. run_id. Process and context tags will be added automatically.
  • severity: Issue severity from 1 to 5, corresponding to: 1 - info, 2 - low, 3 - medium, 4 - high, 5 - critical.
  • description: Description of the issue.
  • span: Associate the issue with a span.

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 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 operation-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_perf_counter

set_perf_counter(name: str) -> None

Measure time delta between span start and this method call using time.perf_counter_ns().

Arguments:

  • name: Counter name.

graphsignal.Span.set_profile

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

Record profiles related to current operation, 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(
    operation: str,
    tags: Optional[dict[str, str]] = None) -> Span

Measure and record sub-operations.

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

Arguments:

  • operation: Operation name.
  • tags: Trace tags. Process and context tags will be added automatically.

Returns:

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

graphsignal.Span.inc_counter_metric

inc_counter_metric(scope: str, 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:

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

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.