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,
auto_instrument: Optional[bool] = True,
record_data_samples: Optional[bool] = True,
upload_on_shutdown: Optional[bool] = True,
debug_mode: Optional[bool] = False) -> None
Configures and initializes the Graphsignal tracer.
All arguments can also be passed via environment variables: GRAPHSIGNAL_{ARG_NAME_UPPERCASE}
. To pass tags
as an 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. Defaults to Graphsignal cloud.deployment
: A unique name to group and identify operations for a particular deployment, version or environment.tags
: Run-level tags to group and filter recorded data.auto_instrument
: Enable/disable automatic instrumentation of libraries and frameworks.record_data_samples
: Enable/disable recording of data samples along with data statistics.upload_on_shutdown
: Enable/disable uploading of outstanding metrics on process or tracer shutdown.debug_mode
: Enable/disable debug logging.
Raises:
ValueError
- When arguments are missing or invalid.
graphsignal.set_tag
set_tag(key: str, value: Any) -> None
Set run-level tags to group and filter recorded data.
Arguments:
key
: Tag key.value
: Tag value. Will be converted to string usingstr()
.
graphsignal.set_context_tag
set_context_tag(key: str, value: Any) -> None
Set context-level tags to group and filter recorded data. Context tags are propagated to all traces in the same context, e.g. a web application request. Run-level tags with same keys will be overwritten.
Arguments:
key
: Tag key.value
: Tag value. Will be converted to string usingstr()
.
graphsignal.start_trace
start_trace(
operation: str,
tags: Optional[dict[str, str]] = None,
options: Optional[TraceOptions] = None) -> Span
Measure and trace operation.
with
context manager can be used around the function call or code segment. Otherwise, stop()
method should be called on the returned Span
object.
Arguments:
operation
: Unique identifier for a function or code segment.tags
: Trace-level tags to group and filter recorded data. Run-level and context-level tags with same keys will be overwritten.options
: Trace sampling options. Seegraphsignal.TraceOptions
for more information.
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,
options: Optional[TraceOptions] = None)
A decorator for measuring and 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 trace.
@graphsignal.trace_function(operation='predict', tags=dict(t1=1))
def predict(x):
return model(x)
Arguments:
operation
: Unique identifier for a function or code segment.tags
: Trace-level tags to group and filter recorded data. Run-level and context-level tags with same keys will be overwritten.options
: Trace sampling options.
graphsignal.current_span
current_span() -> Optional[Span]
Returns current span or None
. Useful for adding information to the Span
in the current context, e.g. user request.
Returns:
Span
- span object representing currently active operation, e.g. inference.
graphsignal.upload
upload(block: Optional[bool] = False) -> None
Performance data is uploaded periodically. Call this method to initiate upload.
Arguments:
block
: If set to trueTrue
, 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.start_trace()
method and should not be created directly.
graphsignal.Span.is_sampling
is_sampling() -> bool
Returns True
if current trace is being recorded.
graphsignal.Span.set_tag
set_tag(key: str, value: Any) -> None
Set trace-level tags to group and filter recorded data. Run-level and context-level tags with same keys will be overwritten.
Arguments:
key
: Tag key.value
: Tag value. Will be converted to string usingstr()
.
graphsignal.Span.set_param
set_param(name: str, value: Any) -> None
Any trace-level parameters. Run-level parameters with same names will be overwritten.
Arguments:
name
: Parameter name.value
: Parameter value. Will be converted to string usingstr()
.
graphsignal.Span.add_exception
add_exception(exc: Optional[Exception] = None, exc_info: Optional[bool] = None) -> None
When with
context manager is used with graphsignal.start_trace()
method, exceptions are automatically reported. For other cases, use this method.
Arguments:
exc
: Exception object.exc_info
: WhenTrue
, thesys.exc_info()
will be called internally.
graphsignal.Span.set_data
set_data(
name: str,
obj: Any,
counts: Optional[dict[str, int]] = None,
record_data_sample: Optional[bool] = True) -> None
Measure any data related to current trace, e.g. input, output, to track data metrics and record data profiles and samples that will be available within traces.
with graphsignal.start_trace('predict') as span:
span.set_data('input', input_data)
To append to data, use graphsignal.Span.append_data
with same parameters instead. obj
must support the +
operator.
Arguments:
name
: Data name, e.g. 'model-input'obj
: Data object. The following types are currently supported:list
,dict
,set
,tuple
,str
,bytes
,numpy.ndarray
,tensorflow.Tensor
,torch.Tensor
.counts
Set data additional data statistics, e.g.token_count
.record_data_sample
: Enable/disable recording of a data sample along with data statistics.
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.
graphsignal.TraceOptions
TraceOptions(
record_samples: bool = True,
record_metrics: bool = True,
enable_profiling: bool = False):
TraceOptions
object can be passed to graphsignal.start_trace()
and @graphsignal.trace_function()
methods. It contains the following options:
record_samples
: Enable/disable sample recording.record_metrics
: Enable/disable RED and data metric recording.enable_profiling
: Enable/disable call and operation-level profiling during trace sampling. Some profilers may add significant overhead. Only top-level traces can be profiled.
Example:
with start_trace('predict', options=TraceOptions(enable_profiling=True)):
pred = model(x)