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

experimental/CHANGELOG.md

@@ -57,6 +57,7 @@ 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/`) [#6807](https://github.com/open-telemetry/opentelemetry-js/issues/6807) @MikeGoldsmith
 * docs(configuration): link the configuration README to the cross-SDK declarative config language support status doc [#6809](https://github.com/open-telemetry/opentelemetry-js/issues/6809) @MikeGoldsmith
 
 ### :house: Internal

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,48 @@
+# 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 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.
+
+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://vendor.endpoint \
+EXAMPLE_API_KEY=$VENDOR_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:latest
+    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,41 @@
+/*
+ * 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();
+  });
+
+  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,58 @@
+file_format: "1.1"
+
+disabled: ${OTEL_SDK_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}
+
+# Configure the W3C propagators explicitly. tracecontext and baggage match the
+# spec default, but the propagator block must be present for any to be applied.
+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:
+    parent_based:
+      root:
+        trace_id_ratio_based:
+          ratio: 1.0
+
+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
+
+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.220.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.220.0",
+    "@opentelemetry/configuration": "0.220.0",
+    "@opentelemetry/sdk-node": "0.220.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"
+    }
+  ]
+}