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 areprofile.cpython
,profile.pytorch
. Profiling is subject to sampling according tosamples_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 usingstr()
.append_uuid
WhenTrue
, appends a UUID to the value, e.g. for provided valuemyval
the resulting tag value will bemyval-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 usingstr()
.append_uuid
WhenTrue
, appends a UUID to the value, e.g. for provided valuemyval
the resulting tag value will bemyval-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 usingstr()
.
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 usingstr()
.
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 areprofile.cpython
,profile.pytorch
. Profiling is subject to sampling according tosamples_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 areprofile.cpython
,profile.pytorch
. Profiling is subject to sampling according tosamples_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 andexc_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 trueTrue
, will block.force
: IfTrue
, 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 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.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_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 usingstr()
.
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.