docs(configuration): add declarative config example for startNodeSDK()

experimental/CHANGELOG.md

@@ -27,6 +27,8 @@ For notes on migrating to 2.x / 0.200.x see [the upgrade guide](doc/upgrade-to-2
 
 ### :books: Documentation
 
+* docs(configuration): add declarative config example (`experimental/examples/declarative-config/`) and document supported fields and current limitations in the configuration package README [#6807](https://github.com/open-telemetry/opentelemetry-js/issues/6807) @MikeGoldsmith
+
 ### :house: Internal
 
 ## 0.219.0

experimental/examples/README.md

@@ -6,9 +6,10 @@ This directory contains examples of how to run real applications with OpenTeleme
 
 These examples are using work in progress metrics packages.
 
-| Name                      | Description                                                                      | Complexity Level |
-| ------------------------- | -------------------------------------------------------------------------------- | ---------------- |
-| [prometheus](prometheus/) | Basic Metric use with Prometheus (`@opentelemetry/exporter-prometheus`) Exporter | Beginner         |
+| Name                                      | Description                                                                                     | Complexity Level |
+| ----------------------------------------- | ----------------------------------------------------------------------------------------------- | ---------------- |
+| [declarative-config](declarative-config/) | End-to-end traces/metrics/logs over OTLP HTTP, configured from a YAML file via `startNodeSDK()` | Beginner         |
+| [prometheus](prometheus/)                 | Basic Metric use with Prometheus (`@opentelemetry/exporter-prometheus`) Exporter                | Beginner         |
 
 ## Contributing
 

experimental/examples/declarative-config/README.md

@@ -0,0 +1,50 @@
+# Declarative Configuration Example
+
+End-to-end example of configuring the Node SDK from a YAML file via
+`OTEL_CONFIG_FILE` and `startNodeSDK()`. No programmatic provider construction:
+the YAML drives traces, metrics, logs, resource attributes, propagators, and
+the (planned) sampler.
+
+## What this demonstrates
+
+- A single `otel-config.yaml` covering traces, metrics, and logs over OTLP HTTP.
+- Environment variable substitution (`${OTEL_EXPORTER_OTLP_ENDPOINT:-...}`,
+  `${EXAMPLE_API_KEY:-}`) so secrets and per-environment values stay out of the
+  YAML.
+- A `parent_based` sampler config (parsed today, applied once
+  [#6506](https://github.com/open-telemetry/opentelemetry-js/issues/6506) lands).
+- W3C `tracecontext` + `baggage` propagators.
+
+See [`../../packages/configuration/README.md`](../../packages/configuration/README.md)
+for the full list of supported fields and current limitations.
+
+## Run it
+
+The example exports to any OTLP HTTP endpoint. The simplest path is the bundled
+collector that prints what it receives.
+
+```sh
+# 1. Start a collector locally (OTLP HTTP receiver on :4318, debug exporter)
+docker compose up -d
+
+# 2. Install deps + start the example
+npm install
+npm start
+```
+
+You should see span, metric, and log entries in the collector's container logs:
+
+```sh
+docker compose logs -f otel-collector
+```
+
+To export to your own backend instead, set `OTEL_EXPORTER_OTLP_ENDPOINT` and
+(optionally) `EXAMPLE_API_KEY`:
+
+```sh
+OTEL_EXPORTER_OTLP_ENDPOINT=https://api.honeycomb.io \
+EXAMPLE_API_KEY=$HONEYCOMB_API_KEY \
+npm start
+```
+
+Tear down the collector with `docker compose down`.

experimental/examples/declarative-config/docker-compose.yaml

@@ -0,0 +1,9 @@
+services:
+  otel-collector:
+    image: otel/opentelemetry-collector-contrib:0.123.0
+    command: ["--config=/etc/otel-collector-config.yaml"]
+    volumes:
+      - "./otel-collector-config.yaml:/etc/otel-collector-config.yaml"
+    ports:
+      - "4318:4318" # OTLP HTTP
+    restart: unless-stopped

experimental/examples/declarative-config/index.ts

@@ -0,0 +1,43 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { trace, metrics } from '@opentelemetry/api';
+import { logs, SeverityNumber } from '@opentelemetry/api-logs';
+import { startNodeSDK } from '@opentelemetry/sdk-node';
+
+// `startNodeSDK()` reads OTEL_CONFIG_FILE (set in package.json's start script)
+// and wires up trace, metric, and log pipelines from the YAML. No programmatic
+// provider construction needed.
+const sdk = startNodeSDK();
+
+const tracer = trace.getTracer('example');
+const meter = metrics.getMeter('example');
+const logger = logs.getLogger('example');
+
+const counter = meter.createCounter('example.requests', {
+  description: 'Demo counter incremented per request',
+});
+
+async function main(): Promise<void> {
+  await tracer.startActiveSpan('example.request', async span => {
+    span.setAttribute('example.kind', 'demo');
+    counter.add(1, { route: '/hello' });
+    logger.emit({
+      severityNumber: SeverityNumber.INFO,
+      body: 'Handled example request',
+      attributes: { route: '/hello' },
+    });
+    span.end();
+  });
+
+  // Give the batch processors a moment to flush before shutdown.
+  await new Promise(resolve => setTimeout(resolve, 1000));
+  await sdk.shutdown();
+}
+
+main().catch(err => {
+  console.error(err);
+  process.exit(1);
+});

experimental/examples/declarative-config/otel-collector-config.yaml

@@ -0,0 +1,21 @@
+receivers:
+  otlp:
+    protocols:
+      http:
+        endpoint: 0.0.0.0:4318
+
+exporters:
+  debug:
+    verbosity: detailed
+
+service:
+  pipelines:
+    traces:
+      receivers: [otlp]
+      exporters: [debug]
+    metrics:
+      receivers: [otlp]
+      exporters: [debug]
+    logs:
+      receivers: [otlp]
+      exporters: [debug]

experimental/examples/declarative-config/otel-config.yaml

@@ -0,0 +1,69 @@
+file_format: "1.1"
+
+# Set OTEL_SDK_DISABLED=true to disable the SDK without code changes.
+disabled: false
+log_level: info
+
+resource:
+  attributes:
+    - name: service.name
+      value: declarative-config-example
+    - name: service.version
+      value: "0.1.0"
+    - name: deployment.environment.name
+      value: ${DEPLOYMENT_ENV:-development}
+
+# Comma-separated list of W3C propagators. tracecontext + baggage is the spec default.
+propagator:
+  composite:
+    - tracecontext: {}
+    - baggage: {}
+
+tracer_provider:
+  processors:
+    - batch:
+        exporter:
+          otlp_http:
+            endpoint: ${OTEL_EXPORTER_OTLP_ENDPOINT:-http://localhost:4318}/v1/traces
+            # Headers support env var substitution so secrets don't live in the YAML.
+            headers:
+              - name: x-example-api-key
+                value: ${EXAMPLE_API_KEY:-}
+            compression: gzip
+            timeout: 10000
+  # Sampler is parsed but not yet applied to the SDK (see #6506). The YAML is
+  # spec-conformant so it will start sampling once that lands.
+  sampler:
+    parent_based:
+      root:
+        trace_id_ratio_based:
+          ratio: 1.0
+      remote_parent_sampled:
+        always_on: {}
+      remote_parent_not_sampled:
+        always_off: {}
+      local_parent_sampled:
+        always_on: {}
+      local_parent_not_sampled:
+        always_off: {}
+
+meter_provider:
+  readers:
+    - periodic:
+        interval: 10000
+        timeout: 5000
+        exporter:
+          otlp_http:
+            endpoint: ${OTEL_EXPORTER_OTLP_ENDPOINT:-http://localhost:4318}/v1/metrics
+            compression: gzip
+            timeout: 10000
+            temporality_preference: cumulative
+
+logger_provider:
+  processors:
+    - batch:
+        exporter:
+          otlp_http:
+            endpoint: ${OTEL_EXPORTER_OTLP_ENDPOINT:-http://localhost:4318}/v1/logs
+            compression: gzip
+            timeout: 10000

experimental/examples/declarative-config/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "declarative-config-example",
+  "version": "0.219.0",
+  "private": true,
+  "description": "Example of configuring the Node SDK from a YAML file via OTEL_CONFIG_FILE + startNodeSDK()",
+  "main": "index.ts",
+  "scripts": {
+    "start": "OTEL_CONFIG_FILE=./otel-config.yaml ts-node index.ts",
+    "align-api-deps": "node ../../../scripts/align-api-deps.js"
+  },
+  "author": "OpenTelemetry Authors",
+  "license": "Apache-2.0",
+  "dependencies": {
+    "@opentelemetry/api": "^1.7.0",
+    "@opentelemetry/api-logs": "0.219.0",
+    "@opentelemetry/configuration": "0.219.0",
+    "@opentelemetry/sdk-node": "0.219.0"
+  },
+  "devDependencies": {
+    "@types/node": "18.19.130",
+    "ts-node": "^10.9.1"
+  }
+}

experimental/examples/declarative-config/tsconfig.json

@@ -0,0 +1,22 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "build",
+    "rootDir": "."
+  },
+  "include": ["./index.ts"],
+  "references": [
+    {
+      "path": "../../../api"
+    },
+    {
+      "path": "../../../experimental/packages/api-logs"
+    },
+    {
+      "path": "../../../experimental/packages/configuration"
+    },
+    {
+      "path": "../../../experimental/packages/opentelemetry-sdk-node"
+    }
+  ]
+}

experimental/packages/configuration/README.md

@@ -127,6 +127,45 @@ One intentional exception in both paths: `AttributeNameValue.type` is **not** de
 ## Supported schema versions
 
 - `1.0`
+- `1.1`
+
+`file_format` must specify a major and minor version (e.g. `"1.0"` or `"1.1"`).
+Newer minor versions of major `1` are accepted with a warning; other major
+versions are rejected.
+
+## Supported fields
+
+The SDK currently wires these YAML fields through to runtime components:
+
+| Section | Fields |
+| --- | --- |
+| Top-level | `disabled`, `log_level`, `attribute_limits` |
+| `resource` | `attributes`, `attributes_list`, `schema_url`, `detection/development.detectors` |
+| `propagator` | `composite`, `composite_list` |
+| `tracer_provider` | `processors` (batch + simple), `limits`, `id_generator` |
+| `meter_provider` | `readers.periodic` (with OTLP HTTP / gRPC exporters), `views` |
+| `logger_provider` | `processors` (batch + simple), `limits` |
+
+OTLP exporter configuration (HTTP and gRPC) honours `endpoint`, `headers`,
+`headers_list`, `tls`, `compression`, `timeout`, `encoding`, plus
+`temporality_preference` and `default_histogram_aggregation` for metrics.
+
+## Current limitations
+
+Spec fields that the SDK does **not** yet apply, even though the YAML is parsed
+and validated:
+
+| Field | Tracking issue |
+| --- | --- |
+| `tracer_provider.sampler` | [#6506](https://github.com/open-telemetry/opentelemetry-js/issues/6506) |
+| `meter_provider.readers.pull` (Prometheus) | [#6063](https://github.com/open-telemetry/opentelemetry-js/issues/6063), [#6426](https://github.com/open-telemetry/opentelemetry-js/issues/6426) |
+| `meter_provider.exemplar_filter` | not yet filed |
+| `tracer_configurator`, `meter_configurator`, `logger_configurator` | not yet filed |
+| Warnings on invalid / unrecognized values | [#6107](https://github.com/open-telemetry/opentelemetry-js/issues/6107) |
+| Third-party component providers (samplers, exporters, propagators) | [#5824](https://github.com/open-telemetry/opentelemetry-js/issues/5824), [#5825](https://github.com/open-telemetry/opentelemetry-js/issues/5825) |
+
+See the [JavaScript Declarative Configuration project board](https://github.com/orgs/open-telemetry/projects/157)
+for the current state of all tracked work.
 
 ## Useful links