feat(metrics): add advisory attributes parameter to metric instruments

- Add experimental `attributes` parameter to MetricAdvice interface
- Implement attribute filtering via ViewRegistry default views
- Only applies when no Views are configured for the instrument
- Views take precedence over advisory attributes when present
- Add comprehensive unit and integration tests
- Update documentation and changelogs

Closes #4365

Author: pratstick

CHANGELOG.md

@@ -14,6 +14,11 @@ For notes on migrating to 2.x / 0.200.x see [the upgrade guide](doc/upgrade-to-2
 
 ### :rocket: Features
 
+* feat(metrics): add advisory attributes parameter to metric instruments [#4365](https://github.com/open-telemetry/opentelemetry-js/issues/4365)
+  * Added experimental `attributes` parameter to `MetricAdvice` for filtering measurement attributes
+  * Only applies when no Views are configured for the instrument
+  * Views take precedence over advisory attributes when present
+
 ### :bug: Bug Fixes
 
 * fix(sdk-metrics): Remove invalid default value for `startTime` param to ExponentialHistogramAccumulation. This only impacted the closurescript compiler. [#5763](https://github.com/open-telemetry/opentelemetry-js/pull/5763) @trentm

api/CHANGELOG.md

@@ -9,6 +9,10 @@ All notable changes to this project will be documented in this file.
 
 ### :rocket: (Enhancement)
 
+* feat(metrics): add advisory attributes parameter to metric instruments [#4365](https://github.com/open-telemetry/opentelemetry-js/issues/4365)
+  * Added experimental `attributes` parameter to `MetricAdvice` interface
+  * Allows specifying an allow-list of attribute keys for metric instruments
+
 * feat(api): improve isValidSpanId, isValidTraceId performance [#5714](https://github.com/open-telemetry/opentelemetry-js/pull/5714) @seemk
 * feat(diag): change types in `DiagComponentLogger` from `any` to `unknown`[#5478](https://github.com/open-telemetry/opentelemetry-js/pull/5478) @loganrosen
 

api/src/metrics/Metric.ts

@@ -35,6 +35,11 @@ export interface MetricAdvice {
    * @experimental
    * An allow-list of attribute keys for this instrument. Only these keys will be kept
    * on measurements recorded by this instrument. If not provided, all attributes are kept.
+   *
+   * @example <caption>only keep 'service' and 'version' attributes</caption>
+   * attributes: ['service', 'version']
+   * @example <caption>keep all attributes (default behavior)</caption>
+   * attributes: undefined
    */
   attributes?: string[];
 }

packages/sdk-metrics/README.md

@@ -36,29 +36,6 @@ const counter = opentelemetry.metrics.getMeter('default').createCounter('foo');
 counter.add(1, { attributeKey: 'attribute-value' });
 ```
 
-### Advisory Attributes Parameter (Experimental)
-
-The Metrics API supports an optional `attributes` advisory parameter in the `advice` configuration when creating instruments. This parameter acts as an allow-list for attribute keys, filtering out all attributes that are not in the specified list:
-
-```js
-const counter = opentelemetry.metrics.getMeter('default').createCounter('filtered-counter', {
-  description: 'A counter with attribute filtering',
-  advice: {
-    attributes: ['service', 'version'], // @experimental: Only these keys will be kept
-  },
-});
-
-// Only 'service' and 'version' attributes will be recorded, others are filtered out
-counter.add(1, { 
-  service: 'api-gateway', 
-  version: '1.0.0', 
-  region: 'us-west', // This will be filtered out
-  method: 'GET'      // This will be filtered out
-});
-```
-
-**Note:** This feature is experimental and may change in future versions. The advisory attributes parameter only applies when no Views are configured for the instrument. If Views are present, they take precedence over the instrument's advisory attributes.
-
 In conditions, we may need to setup an async instrument to observe costly events:
 
 ```js
@@ -102,6 +79,29 @@ const meterProvider = new MeterProvider({
 })
 ```
 
+## Advisory Attributes (Experimental)
+
+The Metrics API supports an optional `attributes` advisory parameter in the `advice` configuration when creating instruments. This parameter acts as an allow-list for attribute keys, filtering out all attributes that are not in the specified list:
+
+```js
+const counter = opentelemetry.metrics.getMeter('default').createCounter('filtered-counter', {
+  description: 'A counter with attribute filtering',
+  advice: {
+    attributes: ['service', 'version'], // @experimental: Only these keys will be kept
+  },
+});
+
+// Only 'service' and 'version' attributes will be recorded, others are filtered out
+counter.add(1, { 
+  service: 'api-gateway', 
+  version: '1.0.0', 
+  region: 'us-west', // This will be filtered out
+  method: 'GET'      // This will be filtered out
+});
+```
+
+**Note:** This feature is experimental and may change in future versions. The advisory attributes parameter only applies when no Views are configured for the instrument. If Views are present, they take precedence over the instrument's advisory attributes.
+
 ## Example
 
 See [examples/prometheus](https://github.com/open-telemetry/opentelemetry-js/tree/main/experimental/examples/prometheus) for an end-to-end example, including exporting metrics.

packages/sdk-metrics/examples/advisory-attributes.js

@@ -18,7 +18,7 @@ import { InstrumentationScope } from '@opentelemetry/core';
 import { InstrumentDescriptor } from '../InstrumentDescriptor';
 import { InstrumentSelector } from './InstrumentSelector';
 import { MeterSelector } from './MeterSelector';
-import { View } from './View';
+import { View, ViewOptions } from './View';
 import { createAllowListAttributesProcessor } from './AttributesProcessor';
 
 export class ViewRegistry {
@@ -50,17 +50,22 @@ export class ViewRegistry {
 
   private _createDefaultView(instrument: InstrumentDescriptor): View {
     // Create default view with instrument's advisory attributes as an allow-list
-    const viewOptions: any = {
+    const viewOptions: ViewOptions = {
       instrumentName: instrument.name,
       instrumentType: instrument.type,
       instrumentUnit: instrument.unit,
     };
-    
+
     // If instrument has advisory attributes, use them as an allow-list
-    if (instrument.advice.attributes && instrument.advice.attributes.length > 0) {
-      viewOptions.attributesProcessors = [createAllowListAttributesProcessor(instrument.advice.attributes)];
+    if (
+      instrument.advice.attributes &&
+      instrument.advice.attributes.length > 0
+    ) {
+      viewOptions.attributesProcessors = [
+        createAllowListAttributesProcessor(instrument.advice.attributes),
+      ];
     }
-    
+
     // Create a view that matches this specific instrument
     return new View(viewOptions);
   }