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

api/src/metrics/Metric.ts

@@ -30,6 +30,15 @@ export interface MetricAdvice {
    * aggregated with a HistogramAggregator.
    */
   explicitBucketBoundaries?: number[];
+
+  /**
+   * @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.
+   *
+   * See: https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#instrument-advisory-parameter-attributes
+   */
+  attributes?: string[];
 }
 
 /**

packages/sdk-metrics/README.md

@@ -36,6 +36,29 @@ 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

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

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+
+/*
+ * This example demonstrates the new advisory attributes parameter for metrics instruments.
+ * The attributes parameter acts as an allow-list for the instrument, filtering out 
+ * all attribute keys that are not in the specified list.
+ */
+
+const { MeterProvider } = require('@opentelemetry/sdk-metrics');
+const { ConsoleMetricExporter } = require('@opentelemetry/sdk-metrics');
+const { PeriodicExportingMetricReader } = require('@opentelemetry/sdk-metrics');
+
+// Create a meter provider with a console exporter
+const meterProvider = new MeterProvider({
+  readers: [
+    new PeriodicExportingMetricReader({
+      exporter: new ConsoleMetricExporter(),
+      exportIntervalMillis: 1000,
+    }),
+  ],
+});
+
+const meter = meterProvider.getMeter('advisory-attributes-example');
+
+// Create a counter with advisory attributes - only 'service' and 'version' keys will be kept
+const requestCounter = meter.createCounter('http_requests_total', {
+  description: 'Total number of HTTP requests',
+  advice: {
+    attributes: ['service', 'version'], // @experimental: Only these keys will be allowed
+  },
+});
+
+// Create a histogram without advisory attributes - all keys will be kept
+const responseTimeHistogram = meter.createHistogram('http_response_time', {
+  description: 'HTTP response time in milliseconds',
+});
+
+// Record some measurements
+console.log('Recording metrics with advisory attributes filtering...\n');
+
+// This will only keep 'service' and 'version' attributes, filtering out 'method' and 'endpoint'
+requestCounter.add(1, {
+  service: 'api-gateway',
+  version: '1.2.3',
+  method: 'GET',      // This will be filtered out
+  endpoint: '/users', // This will be filtered out
+});
+
+requestCounter.add(1, {
+  service: 'user-service',
+  version: '2.1.0',
+  method: 'POST',       // This will be filtered out
+  endpoint: '/auth',    // This will be filtered out
+  region: 'us-west-2',  // This will be filtered out
+});
+
+// This will keep all attributes since no advisory attributes are specified
+responseTimeHistogram.record(150, {
+  service: 'api-gateway',
+  method: 'GET',
+  endpoint: '/users',
+  status_code: '200',
+});
+
+responseTimeHistogram.record(89, {
+  service: 'user-service',
+  method: 'POST',
+  endpoint: '/auth',
+  status_code: '201',
+  region: 'us-west-2',
+});
+
+console.log('Check the console output above to see the filtered attributes!');
+console.log('The http_requests_total metric should only have service and version attributes.');
+console.log('The http_response_time metric should have all attributes.');
+
+// Keep the process running for a bit to see the output
+setTimeout(() => {
+  console.log('\nShutting down...');
+  meterProvider.shutdown();
+}, 2000);

packages/sdk-metrics/src/view/ViewRegistry.ts

@@ -19,6 +19,7 @@ import { InstrumentDescriptor } from '../InstrumentDescriptor';
 import { InstrumentSelector } from './InstrumentSelector';
 import { MeterSelector } from './MeterSelector';
 import { View } from './View';
+import { createAllowListAttributesProcessor } from './AttributesProcessor';
 
 export class ViewRegistry {
   private _registeredViews: View[] = [];
@@ -38,9 +39,32 @@ export class ViewRegistry {
       );
     });
 
+    // If no registered views match, create a default view with instrument's advisory attributes
+    if (views.length === 0) {
+      const defaultView = this._createDefaultView(instrument);
+      return [defaultView];
+    }
+
     return views;
   }
 
+  private _createDefaultView(instrument: InstrumentDescriptor): View {
+    // Create default view with instrument's advisory attributes as an allow-list
+    const viewOptions: any = {
+      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)];
+    }
+
+    // Create a view that matches this specific instrument
+    return new View(viewOptions);
+  }
+
   private _matchInstrument(
     selector: InstrumentSelector,
     instrument: InstrumentDescriptor

packages/sdk-metrics/test/advisory-attributes.integration.test.ts

@@ -0,0 +1,194 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import * as assert from 'assert';
+import { MeterProvider } from '../src/MeterProvider';
+import { TestMetricReader } from './export/TestMetricReader';
+import {
+  defaultInstrumentationScope,
+  testResource,
+} from './util';
+
+describe('Advisory attributes parameter - Integration test', () => {
+  let meterProvider: MeterProvider;
+  let metricReader: TestMetricReader;
+
+  beforeEach(() => {
+    metricReader = new TestMetricReader();
+    meterProvider = new MeterProvider({
+      resource: testResource,
+      readers: [metricReader],
+    });
+  });
+
+  afterEach(() => {
+    metricReader.shutdown();
+  });
+
+  it('should filter attributes based on advisory attributes parameter', async () => {
+    const meter = meterProvider.getMeter(
+      defaultInstrumentationScope.name,
+      defaultInstrumentationScope.version,
+      {
+        schemaUrl: defaultInstrumentationScope.schemaUrl,
+      }
+    );
+
+    // Create counter with advisory attributes
+    const counter = meter.createCounter('test_counter', {
+      description: 'Test counter with advisory attributes',
+      advice: {
+        attributes: ['allowed_key1', 'allowed_key2'], // @experimental
+      },
+    });
+
+    // Record measurements with various attributes
+    counter.add(1, {
+      allowed_key1: 'value1',
+      allowed_key2: 'value2',
+      filtered_key: 'filtered_value', // This should be filtered out
+    });
+
+    counter.add(2, {
+      allowed_key1: 'value3',
+      another_filtered_key: 'another_filtered_value', // This should be filtered out
+    });
+
+    // Collect metrics
+    const metrics = await metricReader.collect();
+
+    assert.strictEqual(metrics.resourceMetrics.scopeMetrics.length, 1);
+
+    const scopeMetrics = metrics.resourceMetrics.scopeMetrics[0];
+    assert.strictEqual(scopeMetrics.metrics.length, 1);
+
+    const metric = scopeMetrics.metrics[0];
+    assert.strictEqual(metric.descriptor.name, 'test_counter');
+    assert.strictEqual(metric.dataPoints.length, 2);
+
+    // Verify that only allowed attributes are present
+    const firstDataPoint = metric.dataPoints[0];
+    assert.deepStrictEqual(firstDataPoint.attributes, {
+      allowed_key1: 'value1',
+      allowed_key2: 'value2',
+    });
+
+    const secondDataPoint = metric.dataPoints[1];
+    assert.deepStrictEqual(secondDataPoint.attributes, {
+      allowed_key1: 'value3',
+    });
+  });
+
+  it('should keep all attributes when no advisory attributes are specified', async () => {
+    const meter = meterProvider.getMeter(
+      defaultInstrumentationScope.name,
+      defaultInstrumentationScope.version,
+      {
+        schemaUrl: defaultInstrumentationScope.schemaUrl,
+      }
+    );
+
+    // Create counter without advisory attributes
+    const counter = meter.createCounter('test_counter_no_filter', {
+      description: 'Test counter without advisory attributes',
+    });
+
+    // Record measurements with various attributes
+    counter.add(1, {
+      key1: 'value1',
+      key2: 'value2',
+      key3: 'value3',
+    });
+
+    // Collect metrics
+    const metrics = await metricReader.collect();
+
+    assert.strictEqual(metrics.resourceMetrics.scopeMetrics.length, 1);
+
+    const scopeMetrics = metrics.resourceMetrics.scopeMetrics[0];
+    assert.strictEqual(scopeMetrics.metrics.length, 1);
+
+    const metric = scopeMetrics.metrics[0];
+    assert.strictEqual(metric.descriptor.name, 'test_counter_no_filter');
+    assert.strictEqual(metric.dataPoints.length, 1);
+
+    // Verify that all attributes are present
+    const dataPoint = metric.dataPoints[0];
+    assert.deepStrictEqual(dataPoint.attributes, {
+      key1: 'value1',
+      key2: 'value2',
+      key3: 'value3',
+    });
+  });
+
+  it('should work with different instrument types', async () => {
+    const meter = meterProvider.getMeter(
+      defaultInstrumentationScope.name,
+      defaultInstrumentationScope.version,
+      {
+        schemaUrl: defaultInstrumentationScope.schemaUrl,
+      }
+    );
+
+    // Test with Histogram
+    const histogram = meter.createHistogram('test_histogram', {
+      description: 'Test histogram with advisory attributes',
+      advice: {
+        attributes: ['service'], // @experimental
+      },
+    });
+
+    histogram.record(10, {
+      service: 'api',
+      endpoint: '/users', // This should be filtered out
+    });
+
+    // Test with UpDownCounter
+    const upDownCounter = meter.createUpDownCounter('test_updown', {
+      description: 'Test updown counter with advisory attributes',
+      advice: {
+        attributes: ['region'], // @experimental
+      },
+    });
+
+    upDownCounter.add(5, {
+      region: 'us-west',
+      instance: 'i-12345', // This should be filtered out
+    });
+
+    // Collect metrics
+    const metrics = await metricReader.collect();
+
+    assert.strictEqual(metrics.resourceMetrics.scopeMetrics.length, 1);
+
+    const scopeMetrics = metrics.resourceMetrics.scopeMetrics[0];
+    assert.strictEqual(scopeMetrics.metrics.length, 2);
+
+    // Verify histogram filtering
+    const histogramMetric = scopeMetrics.metrics.find((m: any) => m.descriptor.name === 'test_histogram');
+    assert.ok(histogramMetric);
+    assert.deepStrictEqual(histogramMetric.dataPoints[0].attributes, {
+      service: 'api',
+    });
+
+    // Verify updown counter filtering
+    const upDownMetric = scopeMetrics.metrics.find((m: any) => m.descriptor.name === 'test_updown');
+    assert.ok(upDownMetric);
+    assert.deepStrictEqual(upDownMetric.dataPoints[0].attributes, {
+      region: 'us-west',
+    });
+  });
+});