Skip to content

Latest commit

 

History

History
183 lines (121 loc) · 7.7 KB

Common.md

File metadata and controls

183 lines (121 loc) · 7.7 KB
Raw

Common Exporter Behavior

This document describes behavior that is common to all New Relic exporters.

User-Agent values

Each exporter MUST report an identifying string and version as part of the User-Agent header when sending data to New Relic.

These values should be appended using the add_version_info API described in the telemetry SDK specification.

The User-Agent values that are appended are always in the format <author>-<exporter_name>-<optional_context>. For New Relic exporters, the author is NewRelic.

Language names are title cased.

Exporter exporter_name Example Value Appended to the User-Agent
opencensus OpenCensus NewRelic-OpenCensus-Exporter/0.1.0
micrometer Micrometer NewRelic-Micrometer-Exporter/0.1.0
kamon Kamon NewRelic-Kamon-Exporter/0.1.0
dropwizard DropWizard NewRelic-DropWizard-Exporter/0.1.0

A full User-Agent example might look like NewRelic-Python-TelemetrySDK/0.2.3 NewRelic-Python-OpenCensus/0.1.0.

Attributes

The origins of measurements exported to New Relic needs to be identifiable in order for them to be useful. Identifying what generated, measured, collected, and transmitted measurements to New Relic is essential in providing the curated experience customers expect. This section describes the attributes that are used to serve this purpose.

The following table is an overview for quick reference of all the attributes defined in the following sub-sections.

Attribute REQUIRED/RECOMMENDED/OPTIONAL
instrumentation.provider REQUIRED
instrumentation.name RECOMMENDED
instrumentation.version RECOMMENDED
collector.name RECOMMENDED
collector.version RECOMMENDED
host.hostname REQUIRED†
service.name REQUIRED†
app.name REQUIRED†
mobileApp.name REQUIRED†
device.model RECOMMENDED†
browserApp.name REQUIRED†
db.name REQUIRED†

†: applies only if annotating an applicable source. See the related sub-section for more information.

Instrumentation

Instruments are used to make measurements of a computing system. The collective application of a set of instruments to comprehensively monitor a computing system is the instrumentation.

For example:

  • Instrumentation for an HTTP library might be the dedicated code in the library that measure its performance (e.g. latency, throughput, errors).
  • Instrumentation for a cluster of Kubernetes pods might be the health check probes.
  • Instrumentation for a computer's CPU might be the embedded sensors measuring its physical state (e.g temperature, speed, power).

Including attributes to identify what instrumentation is used is crucial for interoperability between telemetry systems and the New Relic platform.

instrumentation.provider

All exported measurements MUST contain an instrumentation.provider attribute that identifies the provider of instrumentation.

Example values of this attribute are:

  • newRelic
  • prometheus
  • dropwizard
  • opencensus
  • opentelemetry

instrumentation.name

All exported measurements SHOULD contain an instrumentation.name attribute that identifies the code that is being instrumented if the instrumentation provider exposes this information, otherwise it SHOULD be omitted. This would be the framework, library, or application that uses the instrumentation to report measurements.

Example values of this attribute are:

  • spring-framework
  • python-twisted
  • gorilla/mux

instrumentation.version

All exported measurements SHOULD contain an instrumentation.version attribute set to the version of the instrumentation if the instrumentation provider expose this information, otherwise it SHOULD be omitted.

For libraries, this is the version of the instrumentation, not the version of the library being instrumented.

Example values of this attribute are:

  • v0.1.0
  • 3
  • alpha-v1

Collector

Identifying what collected and transmitted the measurements of a system is important to know. It allows the New Relic platform to inform customers what telemetry systems were used to transmit their data, something that can help debug issues and provide insight into data flows.

A collector can be as simple as the exporter itself, or as complex as a hierarchical system of proxies. Regardless of the complexity or simplicity of the collectors, the measurements they transmit need to identify what collector was the ultimate transmitter. The following attributes are used to make this identification possible.

collector.name

If the exporter is transmitting to New Relic directly then all exported measurements SHOULD contain a collector.name attribute set to the name of the exporter, otherwise it SHOULD be omitted.

Example values of this attribute are:

  • newrelic-dropwizard-reporter
  • newrelic-opentelemetry-go-exporter

collector.version

If the exporter is transmitting to New Relic directly then all exported measurements SHOULD contain a collector.version attribute set to the version of the exporter, otherwise it SHOULD be omitted.

Example values of this attribute are:

  • v0.1.0
  • 3
  • 1.0

Source Kind

A core feature of the New Relic platform is providing a curated observability experience. This is only possible to provide if telemetry includes information about what kind of system it is measuring.

The following attributes are used to identify the kind of the measured system. All exported measurements MUST include at least one of the following attributes and MAY include more than one.

host.hostname

All measurements exported for a host system MUST contain a host.hostname attribute that uniquely identifies that host. Measurements for other kinds of systems MAY also contain this attribute as it can be helpful in describing their origins.

service.name

All measurements exported for a generic computer program (not a mobile or browser application) MUST contain a service.name attribute set to the name of the program.

app.name

All measurements exported for a mobile or browser application MUST contain an app.name attribute set to the name of the application.

mobileApp.name

All measurements exported for a mobile application MUST contain an mobileApp.name attribute set to the name of the mobile application.

device.model

All measurements exported for a mobile application SHOULD contain a device.model attribute set to the mobile device model.

browserApp.name

All measurements exported for a browser application MUST contain an browserApp.name attribute set to the name of the browser application.

db.name

All measurements exported for a database MUST contain an db.name attribute set to the database name.