-
Notifications
You must be signed in to change notification settings - Fork 1.2k
Labels
area:metricsPart of OpenTelemetry MetricsPart of OpenTelemetry MetricsenhancementNew feature or requestNew feature or requestpkg:exporter:stdoutRelated to the stdout exporter packageRelated to the stdout exporter package
Milestone
Description
Add the following OTel Observability for stdoutmetric
:
otel.sdk.exporter.metric_data_point.inflight
otel.sdk.exporter.metric_data_point.exported
otel.sdk.exporter.operation.duration
Observability Implementation Checklist
Based on the project Observability guidelines, ensure the following are completed:
Environment Variable Activation
- Observability features are disabled by default
- Features are activated through the
OTEL_GO_X_OBSERVABILITY
environment variable - Use consistent pattern with
x.Observability.Enabled()
check1 - Follow established experimental feature pattern23
Encapsulation
- Instrumentation is encapsulated within a dedicated
struct
(e.g.,Instrumentation
) - Instrumentation is not mixed into the instrumented component
- Instrumentation code is in its own file or package if complex/reused
- Instrumentation setup doesn't bloat the main component code
Initialization
- Initialization is only done when observability is enabled
- Setup is explicit and side-effect free
- Return errors from initialization when appropriate
- Use the global Meter provider (e.g.,
otel.GetMeterProvider()
) - Include proper meter configuration with:
Performance
- Little to no overhead when observability is disabled
- Expensive operations are only executed when observability is enabled
- When enabled, instrumentation code paths are optimized to reduce allocation/computation overhead
Attribute and Option Allocation Management
- Use
sync.Pool
for attribute slices and options with dynamic attributes - Pool objects are properly reset before returning to pool
- Pools are scoped for maximum efficiency while ensuring correctness
Caching
- Static attribute sets known at compile time are pre-computed and cached
- Common attribute combinations use lookup tables/maps
Benchmarking
- Benchmarks provided for all instrumentation code
- Benchmark scenarios include both enabled and disabled observability
- Benchmark results show impact on allocs/op, B/op, and ns/op (use
b.ReportAllocs()
in benchmarks)
Error Handling and Robustness
- Errors are reported back to caller when possible
- Partial failures are handled gracefully
- Use partially initialized components when available
- Return errors to caller instead of only using
otel.Handle()
- Use
otel.Handle()
only when component cannot report error to user
Context Propagation
- Observability measurements receive the context from the function being measured (don't break context propagation by using
context.Background()
)
Semantic Conventions Compliance
- All metrics follow OpenTelemetry Semantic Conventions
- Use the
otelconv
convenience package for metric semantic conventions - Component names follow semantic conventions
- Use package path scope type as stable identifier for non-standard components
- Component names are stable unique identifiers
- Use global counter for uniqueness if necessary
- Component ID counter is resettable for deterministic testing
Testing
- Use deterministic testing with isolated state
- Restore previous state after tests (
t.Cleanup()
) - Isolate meter provider for testing
- Use
t.Setenv()
for environment variable testing - Reset component ID counter for deterministic component names
- Test order doesn't affect results
Footnotes
-
https://github.com/open-telemetry/opentelemetry-go/blob/e4ab3141123d0811125a69823dbbe4d9ec5a9b8f/exporters/stdout/stdouttrace/internal/observ/instrumentation.go#L101-L103 ↩
-
https://github.com/open-telemetry/opentelemetry-go/blob/e4ab3141123d0811125a69823dbbe4d9ec5a9b8f/exporters/stdout/stdouttrace/internal/x/x.go ↩
-
https://github.com/open-telemetry/opentelemetry-go/blob/e4ab3141123d0811125a69823dbbe4d9ec5a9b8f/sdk/internal/x/x.go ↩
Metadata
Metadata
Assignees
Labels
area:metricsPart of OpenTelemetry MetricsPart of OpenTelemetry MetricsenhancementNew feature or requestNew feature or requestpkg:exporter:stdoutRelated to the stdout exporter packageRelated to the stdout exporter package