Package: dynatrace-metric-utils
dynatrace-metric-utils-pythonPython utility for interacting with
theDynatrace v2 metrics API.InstallationTo install thelatest version from PyPIrun:pipinstalldynatrace-metric-utilsUsageUsing this library to create metric lines is a two-step process. First, create
lines using theDynatraceMetricsFactory. Then, serialize them using
aDynatraceMetricsSerializer. Furthermore, this library contains
constants for use in projects consuming this library. This repository also
containsan example scriptdemonstrating the use of
theDynatraceMetricsFactoryand theDynatraceMetricsSerializer.Metric CreationTo create metrics, call one of the static methods on
theDynatraceMetricsFactory. Available instruments are:Gauge:create_int_gauge/create_float_gaugeCounter:create_int_counter_delta/create_float_counter_deltaSummary:create_int_summary/create_float_summaryIn the simplest form, metric creation looks like this:factory=DynatraceMetricsFactory()metric=factory.create_int_gauge("int-gauge",23)Additionally, it is possible to pass a list of dimensions to the metric upon
creation:metric_dimensions={"dim1":"val1","dim2":"val2",}metric=factory.create_int_gauge("int-gauge",23,metric_dimensions)The dimensions will be added to the serialized metric.
Seethe section on dimension precedencefor more
information.Finally, it is also possible to add a timestamp to the metric:# Passing None for the dimensions will not add any dimensions to the metric.# pass the timestamp as unix-time milliseconds.metric=factory.create_int_gauge("int-gauge",23,None,time.time()*1000)# Alternatively, the dimensions parameter can be skipped and timestamp can be passed as a named parameter.metric=factory.create_int_gauge("int-gauge",23,timestamp=time.time()*1000)If the metric timestamp is omitted or invalid, the Dynatrace server uses its
current time upon ingestion.Metric serializationThe created metrics can then be serialized using
aDynatraceMetricsSerializer:# root level logger.logger=logging.getLogger(__name__)# The logger is optional. If no logger is specified, a logger will be created.factory=DynatraceMetricsFactory(logger.getChild(DynatraceMetricsFactory.__name__))# Create a list of default dimensions which are added to all metrics serialized by this serializer.default_dims={"default1":"value1","default2":"value2"}serializer=DynatraceMetricsSerializer(logger.getChild(DynatraceMetricsSerializer.__name__),"prefix",# metric key prefix, added to all metric namesdefault_dims,# default dimensionsTrue,# whether or not to enrich with Dynatrace metadata"metric-src",# the name of the framework that emits the metrics, e.g. 'opentelemetry')metric=factory.create_int_gauge("int-gauge",23)print(serializer.serialize(metric))# Should result in a line like:# prefix.int-gauge,default1=value1,default2=value2,dt.metrics.source=metric-src gauge,23Common constantsThe constants can be accessed via the staticDynatraceMetricsApiConstantsclass .Currently available constants are:the defaultlocal OneAgent metric API endpoint(default_oneagent_endpoint())the limit for how many metric lines can be ingested in one
request (payload_lines_limit())Dynatrace Metadata enrichmentIf theenrich_with_dynatrace_metadatatoggle in
theDynatraceMetricsSerializerconstructor is set toTrue(=default), an attempt is made to read Dynatrace metadata. On
a host with a running OneAgent, setting this option will collect metadata and
add it as dimensions to all serialized metrics. Metadata typically consist of
the Dynatrace host ID and process group ID. More information on the underlying
feature that is used by the library can be found in
theDynatrace documentation.Dimension precedenceSince there are multiple levels of dimensions (default, metric-specific,
serializer-specific) and duplicate keys are not allowed, there is a specified
precedence in dimension keys. Default dimensions will be overwritten by
metric-specific dimensions, and all dimensions will be overwritten by
serializer-specific dimensions if they share the same key after normalization.
Serializer-specific dimensions include
themetadata dimensions, as well as the
metrics source, which is added as a dimension withdt.metrics.sourceas its
key if themetrics_sourceis set. Note that the serializer-specific
dimensions will only
containdimension keys reserved by Dynatrace.