api.md

Instrumentation Configuration API

Status: Development

• Overview
  • ConfigProvider
    • ConfigProvider operations
      • Get instrumentation config
  • ConfigProperties

Overview

The instrumentation configuration API is part of the declarative configuration interface.

The API allows instrumentation libraries to consume configuration by reading relevant configuration during initialization. For example, an instrumentation library for an HTTP client can read the set of HTTP request and response headers to capture.

It consists of the following main components:

• ConfigProvider is the entry point of the API.
• ConfigProperties is a programmatic representation of a configuration mapping node.

ConfigProvider

ConfigProvider provides access to configuration properties relevant to instrumentation.

Instrumentation libraries access ConfigProvider during initialization. ConfigProvider may be passed as an argument to the instrumentation library, or the instrumentation library may access it from a central place. Thus, the API SHOULD provide a way to access a global default ConfigProvider, and set/register it.

ConfigProvider operations

The ConfigProvider MUST provide the following functions:

• Get instrumentation config

TODO: decide if additional operations are needed to improve API ergonomics

Get instrumentation config

Obtain configuration relevant to instrumentation libraries.

Returns: ConfigProperties representing the .instrumentation configuration mapping node.

If the .instrumentation node is not set, get instrumentation config MUST return nil, null, undefined or another language-specific idiomatic pattern denoting empty.

ConfigProperties

ConfigProperties is a programmatic representation of a configuration mapping node (i.e. a YAML mapping node).

ConfigProperties MUST provide accessors for reading all properties from the mapping node it represents, including:

• scalars (string, boolean, double precision floating point, 64-bit integer)
• mappings, which SHOULD be represented as ConfigProperties
• sequences of scalars
• sequences of mappings, which SHOULD be represented as ConfigProperties
• the set of property keys present

ConfigProperties SHOULD provide access to properties in a type safe manner, based on what is idiomatic in the language.

ConfigProperties SHOULD allow a caller to determine if a property is present with a null value, versus not set.