Instrumentation Scope

Status: Stable

A logical unit of software with which the emitted telemetry can be associated. It is typically the developer’s choice to decide what denotes a reasonable instrumentation scope. The most common approach is to use the name and version of the instrumentation library, with any additional identifying information as part of the scope’s attributes. Other software components can be used too to get name, version and additional attributes, e.g. a module, a package, a class or a plugin.

The instrumentation scope is defined by the (name,version,schema_url,attributes) tuple where version, schema_url, and attributes are optional. This tuple SHOULD uniquely identify the logical unit of software that emits the telemetry. A typical approach to ensure uniqueness is to use the fully qualified name of the emitting software unit (e.g. fully qualified library name or fully qualified class name).

The instrumentation scope is used to obtain a Tracer, Meter, or Logger.

The instrumentation scope’s name SHOULD be specified to identify the InstrumentationScope name.

The instrumentation scope’s optional Schema URL SHOULD identify the Telemetry Schema that the instrumentation’s emitted telemetry conforms to.

The instrumentation scope’s optional attributes provide additional information about the scope. For example for a scope that specifies an instrumentation library an additional attribute may be recorded to denote the URL of the repository URL the library’s source code is stored.

Examples

Here is a non comprehensive list of usage scenarios:

  • Generic instrumentation library with its name, version and attributes containing additional library information.
  • Database access instrumented with its own name and version (e.g. db.system.name). This can be leveraged by APIs abstracting access to different underlying databases, such as JDBC or SqlAlchemy.
  • Client consuming or producing information, using its name, version and id to set InstrumentationScope.
  • Internal application components emitting their own telemetry, relying on InstrumentationScope attributes to differentiate themselves in case multiple instances of the same type exist.