APIs to report numeric metrics (aka time series data). More...

Functions
void	onesdk_metric_delete (onesdk_metric_handle_t metric_handle)
	DEPRECATED. Releases a metric object. More...

onesdk_metric_handle_t	onesdk_integercountermetric_create (onesdk_string_t metric_key, onesdk_string_t unit, onesdk_string_t dimension_name)
	DEPRECATED. Creates a metric to count (sum up) some 64 bit integer values, e.g., number of records inserted in a database. More...

onesdk_metric_handle_t	onesdk_floatcountermetric_create (onesdk_string_t metric_key, onesdk_string_t unit, onesdk_string_t dimension_name)
	DEPRECATED. Creates a metric to count (sum up) some double precision floating point values, e.g., liters pumped into a tank. More...

onesdk_metric_handle_t	onesdk_integergaugemetric_create (onesdk_string_t metric_key, onesdk_string_t unit, onesdk_string_t dimension_name)
	DEPRECATED. Creates a metric to sample (periodically measure) some 64 bit integer value, e.g., number of records in a database sampled every 30 minutes. More...

onesdk_metric_handle_t	onesdk_floatgaugemetric_create (onesdk_string_t metric_key, onesdk_string_t unit, onesdk_string_t dimension_name)
	DEPRECATED. Creates a metric to sample (periodically measure) some double precision floating point value, e.g., number of liters in a tank, sampled every 30 minutes. More...

onesdk_metric_handle_t	onesdk_integerstatisticsmetric_create (onesdk_string_t metric_key, onesdk_string_t unit, onesdk_string_t dimension_name)
	DEPRECATED. Creates a metric to track (measure on each change, event-driven) some 64 bit integer value, e.g., number of records in a database after each insert/delete/merge/etc. More...

onesdk_metric_handle_t	onesdk_floatstatisticsmetric_create (onesdk_string_t metric_key, onesdk_string_t unit, onesdk_string_t dimension_name)
	DEPRECATED. Creates a metric to track (measure on each change, event-driven) some double precision floating point value, e.g., number of liters in a tank after each refilling and (discrete) consumption. More...

void	onesdk_integercountermetric_increase_by (onesdk_metric_handle_t metric_handle, onesdk_int64_t delta, onesdk_string_t dimension)
	DEPRECATED. Increase the counter `metric_handle` for `dimension` by the given `delta`. More...

void	onesdk_floatcountermetric_increase_by (onesdk_metric_handle_t metric_handle, double delta, onesdk_string_t dimension)
	DEPRECATED. Increase the counter `metric_handle` for `dimension` by the given `delta`. More...

void	onesdk_integergaugemetric_set_value (onesdk_metric_handle_t metric_handle, onesdk_int64_t value, onesdk_string_t dimension)
	DEPRECATED. Set the last sampled value for the `metric_handle` for `dimension` to `value`. More...

void	onesdk_floatgaugemetric_set_value (onesdk_metric_handle_t metric_handle, double value, onesdk_string_t dimension)
	DEPRECATED. Set the last sampled value for the `metric_handle` for `dimension` to `value`. More...

void	onesdk_integerstatisticsmetric_add_value (onesdk_metric_handle_t metric_handle, onesdk_int64_t value, onesdk_string_t dimension)
	DEPRECATED. Records the current value for the `metric_handle` for `dimension` to `value`. More...

void	onesdk_floatstatisticsmetric_add_value (onesdk_metric_handle_t metric_handle, double value, onesdk_string_t dimension)
	DEPRECATED. Records the current value for the `metric_handle` for `dimension` to `value`. More...

typedef onesdk_handle_t	onesdk_metric_handle_t
	A handle that refers to a metric object.

Detailed Description

APIs to report numeric metrics (aka time series data).

The SDK supports two metric value types: integer (64 bit signed) and floating point (double precision). You should prefer integers as they are more efficient, unless the loss of precision is unacceptable (but consider using a different unit, e.g. integer microseconds instead of floating point seconds).

There are these different kinds of metrics:

Counter: For all metrics that are counting something like sent/received bytes to/from network. Counters should only be used when tracking things in flow, as opposed to state. It reports the sum only and is the most lightweight metric kind.
Gauge: For metrics that periodically sample a current state, e.g. temperatures, total number of bytes stored on a disk. Gauges report a minimum, maximum and average value (but no sum).
Statistics: For event-driven metrics like the packet size of a network interface. The most heavyweight metric. Reports min, max, average and count.

Each combination of metric value type and kind has its own create-function, named onesdk_<value type><metric kind>metric_create.

When creating a metric, you must provide the following information:

The metric key is a unique identifier of the metric.

Although it is not recommended, you may create multiple metric instances with the same name, as long as you use the same creation function (so that metric value type and kind are the same) and the other metric information is also the same. Otherwise, using the same metric name multiple times is an error. If you do create a metric with the same key multiple times, it is undefined whether distinct handles are returned, but you are required to call onesdk_metric_delete on each one (as if they were distinct). All metrics with the same key will be aggregated together as if you used only one metric instance.

The encoding of the key string can be UTF-8, UTF-16 or ASCII, but only ASCII-compatible characters are allowed. It must not be longer than 100 characters.
The unit is an optional string that will be displayed when browsing for metrics in the Dynatrace UI.
The dimension name: When provided, the metric will have one additional dimension the value of which must be provided when adding values to that metric. When null or empty, the metric has no additional dimension (and a dimension value must not be provided when adding values). Dimension values are like additional labels attached to values, for example a "disk.written.bytes" metric could have a dimension name of "disk-id" and when adding values to it, you could use dimension values like "/dev/sda1".

All metric objects (regardless of type) should be freed using onesdk_metric_delete.

Note: Metrics are not supported when the SDK is intialized using ONESDK_INIT_FLAG_FORKABLE.

Since: Metrics are available since version 1.5.

Deprecated:: From 1.6 on, all metrics-related APIs are deprecated and will be removed in a future release. Refer to https://github.com/Dynatrace/OneAgent-SDK-for-c#metrics for details.

Function Documentation

◆ onesdk_floatcountermetric_create()

onesdk_metric_handle_t onesdk_floatcountermetric_create	(	onesdk_string_t	metric_key,
		onesdk_string_t	unit,
		onesdk_string_t	dimension_name
	)

inline

DEPRECATED. Creates a metric to count (sum up) some double precision floating point values, e.g., liters pumped into a tank.

Parameters

metric_key	An ASCII/UTF-8/UTF-16 string uniquely identifying the metric.
unit	[optional] An informational string to describe the unit of the metric. Used for presentation purposes only.
dimension_name	[optional] If specified, the metric gets an additional dimension. The value for that should be provided when calling onesdk_floatcountermetric_increase_by. The actual dimension name is used for presentation purposes only.

Returns: A handle for the a metric instance or ONESDK_INVALID_HANDLE. If you reused metric_key, the handle value is not guaranteed to be unique.

Since: This function was added in version 1.5.0.

Deprecated:: From 1.6 on, all metrics-related APIs are deprecated and will be removed in a future release. Refer to https://github.com/Dynatrace/OneAgent-SDK-for-c#metrics for details.

See the general metric API documentation for a more detailed conceptual description.

◆ onesdk_floatcountermetric_increase_by()

void onesdk_floatcountermetric_increase_by	(	onesdk_metric_handle_t	metric_handle,
		double	delta,
		onesdk_string_t	dimension
	)

inline

DEPRECATED. Increase the counter metric_handle for dimension by the given delta.

Parameters

metric_handle	A valid floating point counter metric handle, as returned by onesdk_floatcountermetric_create.
delta	Value by which to increase the counter (the total change since the last time onesdk_floatcountermetric_increase_by was called).
dimension	[optional] Dimension value for which to increase the counter. Must be onesdk_nullstr if no `dimension_name` was specified when creating the metric.

Since: This function was added experimentally in version 1.5.0.

Deprecated:: From 1.6 on, all metrics-related APIs are deprecated and will be removed in a future release. Refer to https://github.com/Dynatrace/OneAgent-SDK-for-c#metrics for details.

◆ onesdk_floatgaugemetric_create()

onesdk_metric_handle_t onesdk_floatgaugemetric_create	(	onesdk_string_t	metric_key,
		onesdk_string_t	unit,
		onesdk_string_t	dimension_name
	)

inline

DEPRECATED. Creates a metric to sample (periodically measure) some double precision floating point value, e.g., number of liters in a tank, sampled every 30 minutes.

Parameters

metric_key	An ASCII/UTF-8/UTF-16 string uniquely identifying the metric.
unit	[optional] An informational string to describe the unit of the metric. Used for presentation purposes only.
dimension_name	[optional] If specified, the metric gets an additional dimension. The value for that should be provided when calling onesdk_floatgaugemetric_set_value. The actual dimension name is used for presentation purposes only.

Returns: A handle for the a metric instance or ONESDK_INVALID_HANDLE. If you reused metric_key, the handle value is not guaranteed to be unique.

Since: This function was added experimentally in version 1.5.0.

Deprecated:: From 1.6 on, all metrics-related APIs are deprecated and will be removed in a future release. Refer to https://github.com/Dynatrace/OneAgent-SDK-for-c#metrics for details.

See the general metric API documentation for a more detailed conceptual description.

◆ onesdk_floatgaugemetric_set_value()

void onesdk_floatgaugemetric_set_value	(	onesdk_metric_handle_t	metric_handle,
		double	value,
		onesdk_string_t	dimension
	)

inline

DEPRECATED. Set the last sampled value for the metric_handle for dimension to value.

Parameters

metric_handle	A valid floating point gauge metric handle, as returned by onesdk_floatgaugemetric_create.
value	Current value to which to set the gauge (usually comes from some periodically sampled measurement).
dimension	[optional] Dimension value for which to increase the counter. Must be onesdk_nullstr if no `dimension_name` was specified when creating the metric.

Since: This function was added experimentally in version 1.5.0.

Deprecated:: From 1.6 on, all metrics-related APIs are deprecated and will be removed in a future release. Refer to https://github.com/Dynatrace/OneAgent-SDK-for-c#metrics for details.

◆ onesdk_floatstatisticsmetric_add_value()

void onesdk_floatstatisticsmetric_add_value	(	onesdk_metric_handle_t	metric_handle,
		double	value,
		onesdk_string_t	dimension
	)

inline

DEPRECATED. Records the current value for the metric_handle for dimension to value.

Parameters

metric_handle	A valid floating point statistics metric handle, as returned by onesdk_floatstatisticsmetric_create.
value	Value to record in the statistic (usually comes from a measurement taken after a discrete event that indicates a change in the value).
dimension	[optional] Dimension value for which to increase the counter. Must be onesdk_nullstr if no `dimension_name` was specified when creating the metric.

Since: This function was added experimentally in version 1.5.0.

Deprecated:: From 1.6 on, all metrics-related APIs are deprecated and will be removed in a future release. Refer to https://github.com/Dynatrace/OneAgent-SDK-for-c#metrics for details.

◆ onesdk_floatstatisticsmetric_create()

onesdk_metric_handle_t onesdk_floatstatisticsmetric_create	(	onesdk_string_t	metric_key,
		onesdk_string_t	unit,
		onesdk_string_t	dimension_name
	)

inline

DEPRECATED. Creates a metric to track (measure on each change, event-driven) some double precision floating point value, e.g., number of liters in a tank after each refilling and (discrete) consumption.

Parameters

metric_key	An ASCII/UTF-8/UTF-16 string uniquely identifying the metric.
unit	[optional] An informational string to describe the unit of the metric. Used for presentation purposes only.
dimension_name	[optional] If specified, the metric gets an additional dimension. The value for that should be provided when calling onesdk_floatstatisticsmetric_add_value. The actual dimension name is used for presentation purposes only.

Returns: A handle for the a metric instance or ONESDK_INVALID_HANDLE. If you reused metric_key, the handle value is not guaranteed to be unique.

Since: This function was added experimentally in version 1.5.0.

Deprecated:: From 1.6 on, all metrics-related APIs are deprecated and will be removed in a future release. Refer to https://github.com/Dynatrace/OneAgent-SDK-for-c#metrics for details.

See the general metric API docs for a more detailed conceptual description.

◆ onesdk_integercountermetric_create()

onesdk_metric_handle_t onesdk_integercountermetric_create	(	onesdk_string_t	metric_key,
		onesdk_string_t	unit,
		onesdk_string_t	dimension_name
	)

inline

DEPRECATED. Creates a metric to count (sum up) some 64 bit integer values, e.g., number of records inserted in a database.

Parameters

metric_key	An ASCII/UTF-8/UTF-16 string uniquely identifying the metric.
unit	[optional] An informational string to describe the unit of the metric. Used for presentation purposes only.
dimension_name	[optional] If specified, the metric gets an additional dimension. The value for that should be provided when calling onesdk_integercountermetric_increase_by. The actual dimension name is used for presentation purposes only.

Returns: A handle for the a metric instance or ONESDK_INVALID_HANDLE. If you reused metric_key, the handle value is not guaranteed to be unique.

Since: This function was added in version 1.5.

Deprecated:: From 1.6 on, all metrics-related APIs are deprecated and will be removed in a future release. Refer to https://github.com/Dynatrace/OneAgent-SDK-for-c#metrics for details.

See the general metric API documentation for a more detailed conceptual description.

◆ onesdk_integercountermetric_increase_by()

void onesdk_integercountermetric_increase_by	(	onesdk_metric_handle_t	metric_handle,
		onesdk_int64_t	delta,
		onesdk_string_t	dimension
	)

inline

DEPRECATED. Increase the counter metric_handle for dimension by the given delta.

Parameters

metric_handle	A valid integer counter metric handle, as returned by onesdk_integercountermetric_create.
delta	Value by which to increase the counter (the total change since the last time onesdk_integercountermetric_increase_by was called).
dimension	[optional] Dimension value for which to increase the counter. Must be onesdk_nullstr if no `dimension_name` was specified when creating the metric.

Since: This function was added experimentally in version 1.5.0.

Deprecated:: From 1.6 on, all metrics-related APIs are deprecated and will be removed in a future release. Refer to https://github.com/Dynatrace/OneAgent-SDK-for-c#metrics for details.

◆ onesdk_integergaugemetric_create()

onesdk_metric_handle_t onesdk_integergaugemetric_create	(	onesdk_string_t	metric_key,
		onesdk_string_t	unit,
		onesdk_string_t	dimension_name
	)

inline

DEPRECATED. Creates a metric to sample (periodically measure) some 64 bit integer value, e.g., number of records in a database sampled every 30 minutes.

Parameters

metric_key	An ASCII/UTF-8/UTF-16 string uniquely identifying the metric.
unit	[optional] An informational string to describe the unit of the metric. Used for presentation purposes only.
dimension_name	[optional] If specified, the metric gets an additional dimension. The value for that should be provided when calling onesdk_integergaugemetric_set_value. The actual dimension name is used for presentation purposes only.

Returns: A handle for the a metric instance or ONESDK_INVALID_HANDLE. If you reused metric_key, the handle value is not guaranteed to be unique.

Since: This function was added experimentally in version 1.5.0.

Deprecated:: From 1.6 on, all metrics-related APIs are deprecated and will be removed in a future release. Refer to https://github.com/Dynatrace/OneAgent-SDK-for-c#metrics for details.

See the general metric API documentation for a more detailed conceptual description.

◆ onesdk_integergaugemetric_set_value()

void onesdk_integergaugemetric_set_value	(	onesdk_metric_handle_t	metric_handle,
		onesdk_int64_t	value,
		onesdk_string_t	dimension
	)

inline

DEPRECATED. Set the last sampled value for the metric_handle for dimension to value.

Parameters

metric_handle	A valid integer gauge metric handle, as returned by onesdk_integergaugemetric_create.
value	Current value to which to set the gauge (usually comes from some periodically sampled measurement).
dimension	[optional] Dimension value for which to increase the counter. Must be onesdk_nullstr if no `dimension_name` was specified when creating the metric.

Since: This function was added experimentally in version 1.5.0.

Deprecated:: From 1.6 on, all metrics-related APIs are deprecated and will be removed in a future release. Refer to https://github.com/Dynatrace/OneAgent-SDK-for-c#metrics for details.

◆ onesdk_integerstatisticsmetric_add_value()

void onesdk_integerstatisticsmetric_add_value	(	onesdk_metric_handle_t	metric_handle,
		onesdk_int64_t	value,
		onesdk_string_t	dimension
	)

inline

DEPRECATED. Records the current value for the metric_handle for dimension to value.

Parameters

metric_handle	A valid integer statistics metric handle, as returned by onesdk_integerstatisticsmetric_create.
value	Value to record in the statistic (usually comes from a measurement taken after a discrete event that indicates a change in the value).
dimension	[optional] Dimension value for which to increase the counter. Must be onesdk_nullstr if no `dimension_name` was specified when creating the metric.

Since: This function was added experimentally in version 1.5.0.

Deprecated:: From 1.6 on, all metrics-related APIs are deprecated and will be removed in a future release. Refer to https://github.com/Dynatrace/OneAgent-SDK-for-c#metrics for details.

◆ onesdk_integerstatisticsmetric_create()

onesdk_metric_handle_t onesdk_integerstatisticsmetric_create	(	onesdk_string_t	metric_key,
		onesdk_string_t	unit,
		onesdk_string_t	dimension_name
	)

inline

DEPRECATED. Creates a metric to track (measure on each change, event-driven) some 64 bit integer value, e.g., number of records in a database after each insert/delete/merge/etc.

Parameters

metric_key	An ASCII/UTF-8/UTF-16 string uniquely identifying the metric.
unit	[optional] An informational string to describe the unit of the metric. Used for presentation purposes only.
dimension_name	[optional] If specified, the metric gets an additional dimension. The value for that should be provided when calling onesdk_integerstatisticsmetric_add_value. The actual dimension name is used for presentation purposes only.

Returns: A handle for the a metric instance or ONESDK_INVALID_HANDLE. If you reused metric_key, the handle value is not guaranteed to be unique.

Since: This function was added experimentally in version 1.5.0.

Deprecated:: From 1.6 on, all metrics-related APIs are deprecated and will be removed in a future release. Refer to https://github.com/Dynatrace/OneAgent-SDK-for-c#metrics for details.

See the general metric API documentation for a more detailed conceptual description.

◆ onesdk_metric_delete()

void onesdk_metric_delete ( onesdk_metric_handle_t metric_handle )

DEPRECATED. Releases a metric object.

Parameters

metric_handle A valid metric handle (all types are supported).

Since: This function was added in version 1.5.

Deprecated:: From 1.6 on, all metrics-related APIs are deprecated and will be removed in a future release. Refer to https://github.com/Dynatrace/OneAgent-SDK-for-c#metrics for details.

This function releases the specified metric object. Allocated resources are freed and the handle is invalidated.

An application should call onesdk_metric_delete exactly once for each metric object that it has created.

Functions

Detailed Description

Function Documentation

◆ onesdk_floatcountermetric_create()

◆ onesdk_floatcountermetric_increase_by()

◆ onesdk_floatgaugemetric_create()

◆ onesdk_floatgaugemetric_set_value()

◆ onesdk_floatstatisticsmetric_add_value()

◆ onesdk_floatstatisticsmetric_create()

◆ onesdk_integercountermetric_create()

◆ onesdk_integercountermetric_increase_by()

◆ onesdk_integergaugemetric_create()

◆ onesdk_integergaugemetric_set_value()

◆ onesdk_integerstatisticsmetric_add_value()

◆ onesdk_integerstatisticsmetric_create()

◆ onesdk_metric_delete()