Skip to content

Latest commit

 

History

History
125 lines (103 loc) · 7.13 KB

README.md

File metadata and controls

125 lines (103 loc) · 7.13 KB
Raw

OpenTelemetry Incubator

This artifact contains experimental code related to the trace and metric SDKs.

Declarative Configuration

The declarative configuration interface allows for YAML based file configuration of OpenTelemetrySdk.

Usage:

File yamlConfigFile = new File("/path/to/config.yaml");
OpenTelemetrySdk openTelemetrySdk;
try (FileInputStream yamlConfigFileInputStream = new FileInputStream("/path/to/config.yaml")) {
  openTelemetrySdk = FileConfiguration.parseAndCreate(yamlConfigFileInputStream);
}
// ...proceed with application after successful initialization of OpenTelemetrySdk

Notes:

  • Environment variable substitution is supported as defined in the spec
  • Currently, there is no support for the customization (i.e. AutoConfigurationCustomizerProvider) SPIs defined in opentelemetry-sdk-extension-autoconfigure-spi.
  • Custom SDK extension components which reference the ComponentProvider SPI can be referenced in declarative configuration. Supported types include:
    • Resource
    • SpanExporter
    • MetricExporter
    • LogRecordExporter
    • SpanProcessor
    • LogRecordProcessor
    • TextMapPropagator
    • Sampler
  • You can use declarative configuration with autoconfigure to specify a configuration file via environment variable, e.g. OTEL_EXPERIMENTAL_CONFIG_FILE=/path/to/config.yaml.

View File Configuration

Adds support for file based YAML configuration of Metric SDK Views.

For example, suppose /Users/user123/view.yaml has the following content:

- selector:
    instrument_name: my-instrument
    instrument_type: COUNTER
    instrument_unit: ms
    meter_name: my-meter
    meter_version: 1.0.0
    meter_schema_url: http://example.com
  view:
    name: new-instrument-name
    description: new-description
    aggregation: explicit_bucket_histogram
    aggregation_args:
      bucket_boundaries: [1.0, 2.0, 5.0]
    attribute_keys:
      - foo
      - bar

The equivalent view configuration would be:

SdkMeterProvider.builder()
   .registerView(
       InstrumentSelector.builder()
           .setName("my-instrument")
           .setType(InstrumentType.COUNTER)
           .setUnit("ms")
           .setMeterName("my-meter")
           .setMeterVersion("1.0.0")
           .setMeterSchemaUrl("http://example.com")
           .build(),
       View.builder()
           .setName("new-instrument")
           .setDescription("new-description")
           .setAggregation(Aggregation.explicitBucketHistogram(Arrays.asList(1.0, 2.0, 5.0))
           .setAttributesFilter(key -> new HashSet<>(Arrays.asList("foo", "bar")).contains(key))
           .build());

If using autoconfigure with this artifact on your classpath, it will automatically load a list of view config files specified via environment variable or system property:

System property Environment variable Purpose
otel.experimental.metrics.view-config OTEL_EXPERIMENTAL_METRICS_VIEW_CONFIG List of files containing view configuration YAML [1]

[1] In addition to absolute paths, resources on the classpath packaged with a jar can be loaded. For example, otel.experimental.metrics.view-config=classpath:/my-view.yaml loads the resource /my-view.yaml.

If not using autoconfigure, a file can be used to configure views as follows:

SdkMeterProviderBuilder builder = SdkMeterProvider.builder();
try (FileInputStream fileInputStream = new FileInputStream("/Users/user123/view.yaml")) {
  ViewConfig.registerViews(builder, fileInputStream);
}

The following table describes the set of recognized aggregations:

Aggregation Arguments
default -
sum -
last_value -
drop -
explicit_bucket_histogram bucket_boundaries (optional): List of inclusive upper boundaries for the histogram buckets, in order from lowest to highest.
exponential_bucket_histogram max_buckets (optional): The maximum number of buckets to use for positive or negative recordings.

Additional notes on usage:

  • Many view configurations can live in one file. The YAML is parsed as an array of view configurations.
  • At least one selection field is required, but including all is not necessary. Any omitted fields will result in the default from InstrumentSelector being used.
  • At least one view field is required, but including all is not required. Any omitted fields will result in the default from View being used.
  • Instrument name selection supports the following wildcard characters: * matches 0 or more instances of any character; ? matches exactly one instance of any character. No other advanced selection criteria is supported.