feat(sdk-logs)!: implement scope attributes for logger creation

experimental/CHANGELOG.md

@@ -12,6 +12,8 @@ For notes on migrating to 2.x / 0.200.x see [the upgrade guide](doc/upgrade-to-2
 
 ### :rocket: Features
 
+* feat(sdk-logs)!: add support for attributes in LoggerOptions [#6573](https://github.com/open-telemetry/opentelemetry-js/pull/6573) @pichlermarc
+
 ### :bug: Bug Fixes
 
 * fix(sdk-node): pass all config properties to log record exporters in declarative config [#6708](https://github.com/open-telemetry/opentelemetry-js/pull/6708) @MikeGoldsmith
@@ -88,6 +90,7 @@ For notes on migrating to 2.x / 0.200.x see [the upgrade guide](doc/upgrade-to-2
 * feat(sdk-logs)!: add required `forceFlush()` to `LogRecordExporter` interface [#6356](https://github.com/open-telemetry/opentelemetry-js/pull/6356) @pichlermarc
   * (user-facing): `LogRecordExporter` interface now requires a `forceFlush()` method to be implemented. Custom exporters will need to implement this method to continue working with the Logs SDK.
 * feat(api-logs, sdk-logs)!: add Logger#enabled() [#6371](https://github.com/open-telemetry/opentelemetry-js/pull/6371) @david-luna
+* feat(api-logs)!: rename scopeAttributes to attributes in LoggerOptions [#6573](https://github.com/open-telemetry/opentelemetry-js/pull/6573) @pichlermarc
 * feat(sampler-composite)!: rename `createComposableTraceIDRatioBasedSampler` to `createComposableProbabilitySampler` [#6541](https://github.com/open-telemetry/opentelemetry-js/pull/6541) @ravitheja4531-cell
 
 ### :rocket: Features

experimental/packages/api-logs/src/api/logs.ts

@@ -58,9 +58,17 @@ export class LogsAPI {
   }
 
   /**
-   * Returns a logger from the global logger provider.
+   * Returns a Logger, creating one if one with the given name, version,
+   * schemaUrl, and attributes is not already created.
    *
-   * @returns Logger
+   * Getting a Logger may be expensive, especially when `attributes` are
+   * provided. Reuse Logger instances where possible instead of calling
+   * `getLogger()` on hot paths.
+   *
+   * @param name The name of the logger or instrumentation library.
+   * @param version The version of the logger or instrumentation library.
+   * @param options The options of the logger or instrumentation library.
+   * @returns {@link Logger}
    */
   public getLogger(
     name: string,

experimental/packages/api-logs/src/types/LoggerOptions.ts

@@ -12,7 +12,8 @@ export interface LoggerOptions {
   schemaUrl?: string;
 
   /**
-   * The instrumentation scope attributes to associate with emitted telemetry
+   * The instrumentation scope attributes to associate with emitted telemetry.
+   * These attributes also participate in logger identity.
    */
-  scopeAttributes?: LogAttributes;
+  attributes?: LogAttributes;
 }

experimental/packages/api-logs/src/types/LoggerProvider.ts

@@ -11,13 +11,17 @@ import type { LoggerOptions } from './LoggerOptions';
  */
 export interface LoggerProvider {
   /**
-   * Returns a Logger, creating one if one with the given name, version, and
-   * schemaUrl pair is not already created.
+   * Returns a Logger, creating one if one with the given name, version,
+   * schemaUrl, and attributes is not already created.
+   *
+   * Getting a Logger may be expensive, especially when `attributes` are
+   * provided. Reuse Logger instances where possible instead of calling
+   * `getLogger()` on hot paths.
    *
    * @param name The name of the logger or instrumentation library.
    * @param version The version of the logger or instrumentation library.
    * @param options The options of the logger or instrumentation library.
-   * @returns Logger A Logger with the given name and version
+   * @returns {@link Logger}
    */
   getLogger(name: string, version?: string, options?: LoggerOptions): Logger;
 }

experimental/packages/api-logs/test/noop-implementations/noop-logger-provider.test.ts

@@ -19,10 +19,10 @@ describe('NoopLoggerProvider', () => {
     );
   });
 
-  describe('LoggerOptions#scopeAttributes (LogAttributes)', () => {
-    it('should accept scopeAttributes with primitive values', () => {
+  describe('LoggerOptions#attributes (LogAttributes)', () => {
+    it('should accept attributes with primitive values', () => {
       const logger = loggerProvider.getLogger('logger-name', undefined, {
-        scopeAttributes: {
+        attributes: {
           'service.name': 'api',
           version: 1,
           enabled: true,
@@ -31,9 +31,9 @@ describe('NoopLoggerProvider', () => {
       assert.ok(logger);
     });
 
-    it('should accept scopeAttributes with LogAttribute value types', () => {
+    it('should accept attributes with LogAttribute value types', () => {
       const logger = loggerProvider.getLogger('logger-name', undefined, {
-        scopeAttributes: {
+        attributes: {
           scalar: 'value',
           number: 42,
           bool: true,

experimental/packages/api-logs/test/proxy-implementations/proxy-logger.test.ts

@@ -67,16 +67,16 @@ describe('ProxyLogger', () => {
       ]);
     });
 
-    it('should pass LoggerOptions with scopeAttributes (LogAttributes) to delegate', () => {
-      const scopeAttributes = {
+    it('should pass LoggerOptions with attributes (LogAttributes) to delegate', () => {
+      const attributes = {
         'service.name': 'api',
         version: 1,
         nested: { key: 'value' },
         bytes: new Uint8Array([1, 2, 3]),
       };
       const options = {
         schemaUrl: 'https://opentelemetry.io/schemas/1.7.0',
-        scopeAttributes,
+        attributes,
       };
       const logger = provider.getLogger('test', 'v0', options);
 
@@ -88,8 +88,8 @@ describe('ProxyLogger', () => {
         options,
       ]);
       assert.strictEqual(
-        getLoggerStub.firstCall.args[2]?.scopeAttributes,
-        scopeAttributes
+        getLoggerStub.firstCall.args[2]?.attributes,
+        attributes
       );
     });
   });

experimental/packages/otlp-transformer/src/common/internal.ts

@@ -8,10 +8,10 @@ import type {
   IKeyValue,
   Resource,
 } from './internal-types';
-import type { Attributes } from '@opentelemetry/api';
 import type { InstrumentationScope } from '@opentelemetry/core';
 import type { Resource as ISdkResource } from '@opentelemetry/resources';
 import type { Encoder } from './utils';
+import type { LogAttributes } from '@opentelemetry/api-logs';
 
 export function createResource(
   resource: ISdkResource,
@@ -29,16 +29,27 @@ export function createResource(
 }
 
 export function createInstrumentationScope(
-  scope: InstrumentationScope
+  scope: InstrumentationScope & {
+    attributes?: LogAttributes;
+    droppedAttributesCount?: number;
+  },
+  encoder: Encoder
 ): IInstrumentationScope {
-  return {
+  const result: IInstrumentationScope = {
     name: scope.name,
     version: scope.version,
   };
+
+  if (scope.attributes && Object.keys(scope.attributes).length > 0) {
+    result.attributes = toAttributes(scope.attributes, encoder);
+    result.droppedAttributesCount = scope.droppedAttributesCount ?? 0;
+  }
+
+  return result;
 }
 
 export function toAttributes(
-  attributes: Attributes,
+  attributes: LogAttributes,
   encoder: Encoder
 ): IKeyValue[] {
   return Object.keys(attributes).map(key =>

experimental/packages/otlp-transformer/src/common/protobuf/common-serializer.ts

@@ -199,7 +199,16 @@ export function writeAnyValue(writer: IProtobufWriter, value: AnyValue): void {
  */
 export function writeInstrumentationScope(
   writer: IProtobufWriter,
-  scope: InstrumentationScope,
+  scope: InstrumentationScope &
+    /**
+     * Additional properties that are currently only part of the logs-specific type.
+     * Once InstrumentationScope also includes `attributes` and `droppedAttributesCount`,
+     * we should remove these extensions.
+     */
+    {
+      attributes?: LogAttributes;
+      droppedAttributesCount?: number;
+    },
   fieldNumber: number
 ): void {
   writer.writeTag(fieldNumber, 2);
@@ -216,6 +225,17 @@ export function writeInstrumentationScope(
     writer.writeString(scope.version);
   }
 
+  if (scope.attributes) {
+    // attributes (field 3, repeated KeyValue)
+    writeAttributes(writer, scope.attributes, 3);
+  }
+
+  if (scope.droppedAttributesCount) {
+    // dropped_attributes_count (field 4, uint32)
+    writer.writeTag(4, 0);
+    writer.writeVarint(scope.droppedAttributesCount);
+  }
+
   writer.finishLengthDelimited(start, writer.pos - startPos);
 }
 

experimental/packages/otlp-transformer/src/logs/internal.ts

@@ -16,11 +16,9 @@ import {
   createInstrumentationScope,
   createResource,
   toAnyValue,
-  toKeyValue,
+  toAttributes,
 } from '../common/internal';
 import type { SeverityNumber } from '@opentelemetry/api-logs';
-import type { IKeyValue } from '../common/internal-types';
-import type { LogAttributes } from '@opentelemetry/api-logs';
 
 export function createExportLogsServiceRequest(
   logRecords: ReadableLogRecord[],
@@ -33,29 +31,28 @@ export function createExportLogsServiceRequest(
 
 function createResourceMap(
   logRecords: ReadableLogRecord[]
-): Map<Resource, Map<string, ReadableLogRecord[]>> {
+): Map<
+  Resource,
+  Map<ReadableLogRecord['instrumentationScope'], ReadableLogRecord[]>
+> {
   const resourceMap: Map<
     Resource,
-    Map<string, ReadableLogRecord[]>
+    Map<ReadableLogRecord['instrumentationScope'], ReadableLogRecord[]>
   > = new Map();
 
   for (const record of logRecords) {
-    const {
-      resource,
-      instrumentationScope: { name, version = '', schemaUrl = '' },
-    } = record;
+    const { resource, instrumentationScope } = record;
 
     let ismMap = resourceMap.get(resource);
     if (!ismMap) {
       ismMap = new Map();
       resourceMap.set(resource, ismMap);
     }
 
-    const ismKey = `${name}@${version}:${schemaUrl}`;
-    let records = ismMap.get(ismKey);
+    let records = ismMap.get(instrumentationScope);
     if (!records) {
       records = [];
-      ismMap.set(ismKey, records);
+      ismMap.set(instrumentationScope, records);
     }
     records.push(record);
   }
@@ -73,7 +70,10 @@ function logRecordsToResourceLogs(
       resource: processedResource,
       scopeLogs: Array.from(ismMap, ([, scopeLogs]) => {
         return {
-          scope: createInstrumentationScope(scopeLogs[0].instrumentationScope),
+          scope: createInstrumentationScope(
+            scopeLogs[0].instrumentationScope,
+            encoder
+          ),
           logRecords: scopeLogs.map(log => toLogRecord(log, encoder)),
           schemaUrl: scopeLogs[0].instrumentationScope.schemaUrl,
         };
@@ -91,7 +91,7 @@ function toLogRecord(log: ReadableLogRecord, encoder: Encoder): ILogRecord {
     severityText: log.severityText,
     body: toAnyValue(log.body, encoder),
     eventName: log.eventName,
-    attributes: toLogAttributes(log.attributes, encoder),
+    attributes: toAttributes(log.attributes, encoder),
     droppedAttributesCount: log.droppedAttributesCount,
     flags: log.spanContext?.traceFlags,
     traceId: encoder.encodeOptionalSpanContext(log.spanContext?.traceId),
@@ -104,12 +104,3 @@ function toSeverityNumber(
 ): ESeverityNumber | undefined {
   return severityNumber as number | undefined as ESeverityNumber | undefined;
 }
-
-export function toLogAttributes(
-  attributes: LogAttributes,
-  encoder: Encoder
-): IKeyValue[] {
-  return Object.keys(attributes).map(key =>
-    toKeyValue(key, attributes[key], encoder)
-  );
-}

experimental/packages/otlp-transformer/src/metrics/internal.ts

@@ -50,7 +50,7 @@ export function toScopeMetrics(
 ): IScopeMetrics[] {
   return Array.from(
     scopeMetrics.map(metrics => ({
-      scope: createInstrumentationScope(metrics.scope),
+      scope: createInstrumentationScope(metrics.scope, encoder),
       metrics: metrics.metrics.map(metricData => toMetric(metricData, encoder)),
       schemaUrl: metrics.scope.schemaUrl,
     }))

experimental/packages/otlp-transformer/src/trace/internal.ts

@@ -152,7 +152,10 @@ function spanRecordsToResourceSpans(
         );
 
         scopeResourceSpans.push({
-          scope: createInstrumentationScope(scopeSpans[0].instrumentationScope),
+          scope: createInstrumentationScope(
+            scopeSpans[0].instrumentationScope,
+            encoder
+          ),
           spans: spans,
           schemaUrl: scopeSpans[0].instrumentationScope.schemaUrl,
         });