API Reference

This page contains the full reference to the API of the telemetry framework.

Configuration

telemetry

telemetry.configure

This method takes a BaseConfig object and configures all exporters from that configuration.

telemetry.configure_from_env

This method takes no arguments and will generate the configuration using BaseConfig.from_env() and then calling the configure method from it.

telemetry.config.BaseConfig

This class represents the base class for all the configuration of the telemetry.

BaseConfig.__init__()

Create a default BaseConfig object

BaseConfig.from_env()

Create a configuration from the environment variables. The configuration parameters can be found in How to configure telemetry from the environment

BaseConfig.resource

This field represents the Resource object used by OpenTelemetry to differentiate between multiple services.

BaseConfig.loglevel

This field represents the default loglevel used to configure all the loggers.

BaseConfig.formatter

This field represents the formatter used by the handler to format messages.

telemetry.config.TestConfig

Configuration used for testing

TestConfig.from_env()

Returns a test config with specific configuration for testing from environment.

Warning

This is for internal purposes, it does not include the generic configuration and so it will not take into account the resource, loglevel or formatter.

telemetry.config.HttpConfig

This configuration is used for http exporters.

HttpConfig.__init__()

Constructs an HttpConfig, it takes between 0 and 2 arguments. The first argument is the base endpoint, it should be set unless you manually set all the three endpoints (otherwise it will raise an error during the configuration). The second argument is used to enforce the slash if your endpoint contains a slash (otherwise it will be automatically removed with a warning).

HttpConfig.endpoint

Server of all HTTP endpoints.

HttpConfig endpoints / suffixes

An HttpConfig has 3 variables that can be set, and are used to compute the final endpoints. These variables are suffix_metrics, suffix_traces, suffix_logs. They are appended to the base endpoint to get the final endpoints, that one can get using the metrics_endpoint, traces_endpoint and logs_endpoint.

Alternatively, if you don’t want the append behaviour, you can just set the properties using the setter (see Python @property and @variable.setter documentation for more on how properties work).

HttpConfig.from_env()

Returns an http config with specific configuration for http exporters from environment.

Warning

This is for internal purposes, it does not include the generic configuration and so it will not take into account the resource, loglevel or formatter.

Unit Testing

Metrics Unit Testing (telemetry.metrics)

get_test_reader

Returns the object that contains all the generated metrics, it is an instance of an InMemoryMetricReader.

MetricResult

A metric result represents a metric (with a name, attributes and a value).

CollectedMetrics

A collected metrics is a list of metrics that can either be generated by the code or from an expected list of metrics.

Note

The inner metrics list must be sorted for the functions to properly work.

CollectedMetrics.get_metric

Returns the metric associated with the specified name and attributes.

CollectedMetrics.includes

Checks that the given metrics are all present in the metrics of the self object. It also checks that the value matches by a maximum difference of tolerance that you can set in the arguments.

It returns whether they match followed by an error message (or None if there is no difference).

CollectedMetrics.as_scheme

This returns the metrics in a human readable format. This format can also be used to generate back the list of metrics.

CollectedMetrics.from_scheme

This generate a CollectedMetrics object from a scheme.

CollectedMetrics.from_metrics_data

This generate a CollectedMetrics object from metrics data (these come from a metrics reader).

CollectedMetrics.from_reader

This generate a CollectedMetrics object from the metrics reader.

CollectedMetrics.verify_scheme

This verifies that the data in the metrics reader include the scheme data, with the specified tolerance. You can parametrize the error messages printed using the log level, that is either full or only error message. The full mode displays both the error message and both expected and found metrics as schemes. The simple error mode displays only the error message.

Metrics Unit Testing (telemetry.metrics)

get_test_reader

Returns the object that contains all the generated metrics, it is an instance of an InMemoryMetricReader.

MetricResult

A metric result represents a metric (with a name, attributes and a value).

CollectedMetrics

A collected metrics is a list of metrics that can either be generated by the code or from an expected list of metrics.

Note

The inner metrics list must be sorted for the functions to properly work.

CollectedMetrics.get_metric

Returns the metric associated with the specified name and attributes.

CollectedMetrics.includes

Checks that the given metrics are all present in the metrics of the self object. It also checks that the value matches by a maximum difference of tolerance that you can set in the arguments.

It returns whether they match followed by an error message (or None if there is no difference).

CollectedMetrics.as_scheme

This returns the metrics in a human readable format. This format can also be used to generate back the list of metrics.

CollectedMetrics.from_scheme

This generate a CollectedMetrics object from a scheme.

CollectedMetrics.from_metrics_data

This generate a CollectedMetrics object from metrics data (these come from a metrics reader).

CollectedMetrics.from_reader

This generate a CollectedMetrics object from the metrics reader.

CollectedMetrics.verify_scheme

This verifies that the data in the metrics reader include the scheme data, with the specified tolerance. You can parametrize the error messages printed using the log level, that is either full or only error message. The full mode displays both the error message and both expected and found metrics as schemes. The simple error mode displays only the error message.

Logging Unit Testing (telemetry.logging)

get_test_handler

Returns the object that contains all the generated log records, it is an instance of a TestLoggingHandler, and contains clear and get_sent_records methods to get the log records.

VirtualLog

Objects of this class represents the fundamental data of logs. It contains the message, loglevel and log extra parameters.

VirtualLogRecords

It represents the list of virtual logs.

Note

The inner logs list is sorted by time of logs.

VirtualLogRecords.includes_args_and_matches_with

Checks that the logs of the current object are equal by inclusion to the logs of the input object. Two logs are said to be equal by inclusion if they have the same loglevel, the same message and if the arguments of the log in self includes all the arguments of the log in other. By include, we mean that the argument exists and has the same value (by string comparison).

It returns whether this works, and an error message (or none if no error did happen.

VirtualLogRecords.as_scheme

This returns the logs in a human readable format. This format can also be used to generate back the list of logs.

VirtualLogRecords.from_scheme

This generates a VirtualLogRecords object from a scheme.

VirtualLogRecords.from_records

This generates a VirtualLogRecords object from a list of records.

VirtualLogRecords.from_handler

This generates a VirtualLogRecords object from the log handler.

VirtualLogRecords.verify_scheme

This verifies that the data in the handler include the scheme data. You can parametrize the error messages printed using the log level, that is either full or only error message. The full mode displays both the error message and both expected and found metrics as schemes. The simple error mode displays only the error message.

Traces Unit Testing (telemetry.traces)

get_test_exporter

Returns the InMemorySpanExporter used in testing configurations.

group_intervals

This method takes a list of objects that have both a start_time and end_time property and groups them by equivalence of time (that is if two objects have the same start and ending time, they are in the same list). Furthermore, it returns them sorted by starting time and then by ending time.

This method is useful to check if two spans match as some sub elements might be time-equivalent and you need to greedily match time-equivalent objects.

VirtualEvent / VirtualSpan

These objects represent events and spans from traces, as a tree-like structure. They provide match_with functions to verify that they match.

VirtualContext

This function represents a list of span. It has a as_span method that returns a VirtualSpan asif the spans where subspans of a root span. It has a match_with function to verify it matches another context. It also provides as usual as_scheme, from_scheme, from_spans, from_exporter and verify_scheme methods.