Skip to content

Latest commit

 

History

History
201 lines (144 loc) · 8.11 KB

capabilities.md

File metadata and controls

201 lines (144 loc) · 8.11 KB

Telemetry SDK Capabilities

The Telemetry SDK is capable of sending multiple types of telemetry.

Metrics

The Telemetry SDK implements the New Relic Metric Data Model. For detailed information about the Metric model, please see the public documentation.

The SDK must support two primary use cases:

  1. It must be possible to construct them with pre-computed values, and the SDK must be capable of serializing them for transport to New Relic.
  2. The SDK must provide aggregation functionality for each of New Relic's supported metric types. The appropriate aggregation function is different for each metric type.

Metric Types

The SDK must provide a representation of each of New Relic's supported metric types: Count, Gauge, and Summary. These representations should be idiomatic for the language of the SDK.

All metric types have these common fields:

field type notes
name text This is the name of a metric.
attributes dictionary/map/hash A map of key/value pairs associated with this metric. Values can be a string, numeric, or boolean.
timestamp timestamp A timestamp is required on every metric. It may be omitted if it is included in the metric batch.

Count

In addition to the common fields, the count metric type has the following fields:

field type notes
value numeric Must be positive.
interval numeric Length of the time window. Must be positive.

It must be possible to construct a count metric with a value.

When aggregating, it must be possible to set the value of an existing count metric, and to increment the value by an arbitrary amount.

An example:

def setValue(self, value):
    self.value = value;

def incrementValue(self, value):
    self.value += value;

Gauge

In addition to the common fields, the gauge metric type has the following fields:

field type
value numeric

It must be possible to construct a gauge metric with a value and timestamp.

When aggregating, it must also be possible to set the value of an existing gauge metric. When the value is set, the timestamp field must be set to the current time.

An example:

func (g *Gauge) Value(val float64) {
    g.Value = val
    g.Timestamp = time.Now()
}

Summary

In addition to the common fields, the summary metric type has the following fields:

field type notes
min numeric This field is optional. When serialized, it may be omitted or the value may be null.
max numeric This field is optional. When serialized, it may be omitted or the value may be null.
count integer
sum numeric
interval numeric Length of the time window. Must be positive. Serializes to a whole number of milliseconds.

It must be possible to construct a summary metric with a min, max, count, and sum.

When aggregating, it must be possible to adjust all of these value fields together. An example:

public void record(double value) {
    this.count += 1;
    this.sum += value;
    this.max = Math.max(this.max, value);
    this.min = Math.min(this.min, value);
}

When the fields of a summary are serialized, the min, max, count, and sum are combined into a single JSON object as the value field.

Metric Batch

A metric batch is a batch that contains only metrics. Metric batches can contain a mixture of metric types.

Spans

The Telemetry SDK implements the New Relic Span Data Model. For detailed information about the Span model, please see the public documentation.

The SDK must provide a representation of a span with the following fields. It must be possible to serialize this representation for transport to New Relic.

The SDK must allow setting all of these fields on a span:

field type notes
id string required
trace id string required
timestamp timestamp required
duration numeric optional; default to null
name string optional; default to null
parent id string optional; default to null
service name string optional; default to null

Span Batch

A span batch is a batch that contains only spans.

Events

The Telemetry SDK implements an abstraction for sending custom events that follows the data model convention for spans and metrics.

SDKs sending events must allow for the specification of "common" attributes. Common attributes will be attached to every event individually inside of the SDK since the current Event API does not allow specification of common attributes via the API payload.

For detailed information about the Event API, please see the public documentation.

The Telemetry SDK must use the following HTTP path for the Event API: /v1/accounts/events

The SDK must provide a representation of an event with the following fields. It must be possible to serialize this representation for transport to New Relic.

field type notes
eventType string required
timestamp timestamp required, but the SDK should provide a default value of the current time
attributes dictionary/map/hash A map of key/value pairs associated with this event. Values can be a string, numeric, or boolean.

Event Batch

An event batch is a batch that contains only events.

Logs

The Telemetry SDK provides an API for sending log entries to New Relic's Log API. This implementation is not recommended for sending high-throughput logs to New Relic. See this blog post for details.

For detailed information about the Log API, please see the public documentation

By default, the Telemetry SDK must use the following HTTP path for the Log API: /log/v1/

The SDK must provide a representation of a log entry with the following fields. It must be possible to serialize this representation for transport to New Relic.transport

field type notes
timestamp timestamp required, but the SDK should provide a default value of the current time
message string technically optional, but strongly suggested
attributes dictionary/map/hash A map of key/value pairs associated with this event. Values can be a string, numeric, or boolean.

Note: There are a variety of additional standard attributes that may be provided for, based on the conventions described in the exporter specification.

Batches

A batch is a data structure containing multiple data points of the same telemetry type. The batch should also contain a map of common attributes that apply to all data points in the batch.

If the same attribute key exists in both the batch attributes and on a data point within the batch, the data point's attribute will take precedence in the New Relic back end.

Batches are a convenient way to serialize data into the payload used for communication with New Relic.

Sending

The SDK must provide the means to send batches to New Relic in a way that handles communication failures using the recommended strategy.