Python API Reference

graphsignal.configure

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

Configures and initializes the agent.

All arguments can also be passed via environment variables: GRAPHSIGNAL_{ARG_NAME_UPPERCASE}. To pass tags as 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. Default to Graphsignal cloud.
  • deployment: A unique name to group and identify endpoints for a particular deployment, version or environment.
  • tags: Run-level tags to identify runs. These tags will be inherited by the traces.
  • debug_mode: Enable/disable debug output.

graphsignal.set_tag

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

Run-level tags to identify runs. These tags will be inherited by the traces.

Arguments:

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

Raises:

  • ValueError - When arguments are missing or invalid.

graphsignal.set_param

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

Log any parameters for the run, e.g. a Python script argument. Parameters will be recorded in the traces.

Arguments:

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

Raises:

  • ValueError - When arguments are missing or invalid.

graphsignal.start_trace

start_trace(
    endpoint: str,
    tags: Optional[dict[str, str]] = None,
    options: Optional[TraceOptions] = None) -> EndpointTrace

Measure and trace execution.

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

Arguments:

  • endpoint: Unique identifier for a function or code segment.
  • tags: Trace-level tags to identify runs and/or traces. Run-level tags with same keys will be overwritten.
  • options: Trace sampling options. See graphsignal.TraceOptions for more information.

Returns:

  • EndpointTrace - trace object representing currently active execution, e.g. inference.

graphsignal.trace_function

trace_function(
    endpoint: Optional[str],
    tags: Optional[dict[str, str]] = None,
    options: Optional[TraceOptions] = None)

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

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

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

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

Arguments:

  • endpoint: Unique identifier for a function or code segment.
  • tags: Trace-level tags to identify runs and/or traces. Run-level tags with same keys will be overwritten.
  • options: Trace sampling options.

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

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

graphsignal.EndpointTrace

EndpointTrace object represent currently active execution. It is returned by start_trace method and should not be created directly.

graphsignal.EndpointTrace.is_sampling

is_sampling() -> bool

Returns True if current trace is being recorded.

graphsignal.EndpointTrace.set_tag

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

Trace-level tags to identify runs and/or traces. Run-level tags with same keys will be overwritten.

Arguments:

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

Raises:

  • ValueError - When arguments are missing or invalid.

graphsignal.EndpointTrace.set_exception

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

When with context manager is used with start_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.

Raises:

  • ValueError - When arguments are missing or invalid.

graphsignal.EndpointTrace.set_data

set_data(name: str, obj: Any) -> None

Measure any data related to current trace to track data metrics and record data profiles that will be available within traces.

with graphsignal.start_trace(endpoint='predict') as trace:
    trace.set_data('input', input_data)

No raw data is recorded by the agent, only statistics such as size, shape or number of missing values.

Arguments:

  • name: Data name, e.g. 'model-input'
  • data: Data object. The following types are currently supported: list, dict, set, tuple, str, bytes, numpy.ndarray, tensorflow.Tensor, torch.Tensor.

Raises:

  • ValueError - When arguments are missing or invalid.

graphsignal.EndpointTrace.stop

stop() -> None

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

graphsignal.TraceOptions

TraceOptions(
    auto_sampling: bool = True, 
    ensure_sample: bool = False, 
    enable_profiling: bool = False, 
    enable_missing_value_detection: bool = True):

TraceOptions object can be passed to start_trace and trace_function methods. It contains the following options:

  • auto_sampling: Enable/disable automatic sampling of traces. Traces will be recorded initially as well as periodically.
  • ensure_sample: Sample current trace. The number of ensured samples is limited per time interval.
  • enable_profiling: Enable/disable call and operation-level profiling during trace sampling. Some profilers may add significant overhead.
  • enable_missing_value_detection: Enable/disable missing value detection on every trace for the data passed to EndpointTrace.set_data method.

Example:

with start_trace(endpoint='predict', options=TraceOptions(enable_profiling=True)):
    pred = model(x)

graphsignal.callbacks.keras.GraphsignalCallback

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

Keras callback interface for automatic measurement.

Usage: model.fit(..., callbacks=[GraphsignalCallback()]) or model.predict(..., callbacks=[GraphsignalCallback()]).

See Model class for more information on adding callbacks.

Arguments:

  • tags: Any additional information to identify the run.

graphsignal.callbacks.pytorch_lightning.GraphsignalCallback

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

PyTorch Lightning callback for automatic measurement and recording.

Usage: Trainer(..., callbacks=[GraphsignalCallback()]).

See Trainer class for more information on adding callbacks.

Arguments:

  • tags: Any additional information to identify traces.