feat(sdk-logs): Add FilteringLogRecordProcessor

experimental/CHANGELOG.md

@@ -41,6 +41,7 @@ For notes on migrating to 2.x / 0.200.x see [the upgrade guide](doc/upgrade-to-2
 * feat(opentelemetry-configuration): parse meter provider from config file [#6000](https://github.com/open-telemetry/opentelemetry-js/pull/6000) @maryliag
 * feat(opentelemetry-configuration): add backup options for certificates and endpoints [#6038](https://github.com/open-telemetry/opentelemetry-js/pull/6038) @maryliag
 * feat(opentelemetry-configuration): add backups for compression, timeout, headers [#6058](https://github.com/open-telemetry/opentelemetry-js/pull/6058) @JamieDanielson
+* feat(sdk-logs): add the `FilteringLogRecordProcessor` including the ability to filter by minimum severity and trace [#5991](https://github.com/open-telemetry/opentelemetry-js/pull/5991) @JacksonWeber
 
 ### :bug: Bug Fixes
 

experimental/packages/sdk-logs/README.md

@@ -57,6 +57,68 @@ logger.emit({
 Logs configuration is a merge of both the user supplied configuration and the default
 configuration as specified in [config.ts](./src/config.ts)
 
+## Filtering Log Records
+
+Use the `FilteringLogRecordProcessor` to drop log records by severity or trace sampling before they reach exporters. Wrap your existing processor so only logs that pass the filter are forwarded.
+
+### Minimum Severity Filtering
+
+```js
+const {
+  LoggerProvider,
+  SimpleLogRecordProcessor,
+  FilteringLogRecordProcessor,
+} = require('@opentelemetry/sdk-logs');
+const { SeverityNumber } = require('@opentelemetry/api-logs');
+
+const loggerProvider = new LoggerProvider({
+  processors: [
+    new FilteringLogRecordProcessor(
+      new SimpleLogRecordProcessor(exporter),
+      { minimumSeverity: SeverityNumber.WARN }
+    ),
+  ],
+});
+```
+
+- Logs with `severityNumber >= minimumSeverity` are exported.
+- Logs with `severityNumber = UNSPECIFIED` (0) or undefined always bypass the filter.
+- Default minimum severity is `UNSPECIFIED` (no filtering).
+
+### Trace-Based Filtering
+
+```js
+const loggerProvider = new LoggerProvider({
+  processors: [
+    new FilteringLogRecordProcessor(
+      new SimpleLogRecordProcessor(exporter),
+      { traceBased: true }
+    ),
+  ],
+});
+```
+
+- Logs associated with **sampled traces** (`TraceFlags.SAMPLED` set) are exported.
+- Logs associated with **unsampled traces** are dropped.
+- Logs **without trace context** bypass the filter and are exported.
+- Default is `false` (no trace-based filtering).
+
+### Combined Filtering
+
+```js
+const loggerProvider = new LoggerProvider({
+  processors: [
+    new FilteringLogRecordProcessor(
+      new SimpleLogRecordProcessor(exporter),
+      {
+        minimumSeverity: SeverityNumber.WARN,
+        traceBased: true,
+      }
+    ),
+  ],
+});
+```
+
 ## Example
 
 See [examples/logs](https://github.com/open-telemetry/opentelemetry-js/tree/main/experimental/examples/logs)

experimental/packages/sdk-logs/src/export/FilteringLogRecordProcessor.ts

@@ -0,0 +1,83 @@
+/*
+ * 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 {
+  Context,
+  TraceFlags,
+  isSpanContextValid,
+  trace,
+} from '@opentelemetry/api';
+import { SeverityNumber } from '@opentelemetry/api-logs';
+
+import { LogRecordProcessor } from '../LogRecordProcessor';
+import type { SdkLogRecord } from './SdkLogRecord';
+
+export interface FilteringLogRecordProcessorConfig {
+  minimumSeverity?: SeverityNumber;
+  traceBased?: boolean;
+}
+
+/**
+ * LogRecordProcessor that applies severity- and trace-based filtering before
+ * delegating to another processor.
+ */
+export class FilteringLogRecordProcessor implements LogRecordProcessor {
+  private readonly _minimumSeverity: SeverityNumber;
+  private readonly _traceBased: boolean;
+
+  constructor(
+    private readonly _delegate: LogRecordProcessor,
+    config: FilteringLogRecordProcessorConfig = {}
+  ) {
+    this._minimumSeverity =
+      config.minimumSeverity ?? SeverityNumber.UNSPECIFIED;
+    this._traceBased = config.traceBased ?? false;
+  }
+
+  forceFlush(): Promise<void> {
+    return this._delegate.forceFlush();
+  }
+
+  shutdown(): Promise<void> {
+    return this._delegate.shutdown();
+  }
+
+  onEmit(logRecord: SdkLogRecord, context?: Context): void {
+    const severity = logRecord.severityNumber ?? SeverityNumber.UNSPECIFIED;
+    if (
+      severity !== SeverityNumber.UNSPECIFIED &&
+      severity < this._minimumSeverity
+    ) {
+      return;
+    }
+
+    if (this._traceBased) {
+      const spanContext =
+        logRecord.spanContext ??
+        (context ? trace.getSpanContext(context) : undefined);
+
+      if (spanContext && isSpanContextValid(spanContext)) {
+        const isSampled =
+          (spanContext.traceFlags & TraceFlags.SAMPLED) === TraceFlags.SAMPLED;
+        if (!isSampled) {
+          return;
+        }
+      }
+    }
+
+    this._delegate.onEmit(logRecord, context);
+  }
+}

experimental/packages/sdk-logs/src/index.ts

@@ -29,3 +29,7 @@ export type { LogRecordExporter } from './export/LogRecordExporter';
 export { SimpleLogRecordProcessor } from './export/SimpleLogRecordProcessor';
 export { InMemoryLogRecordExporter } from './export/InMemoryLogRecordExporter';
 export { BatchLogRecordProcessor } from './platform';
+export {
+  FilteringLogRecordProcessor,
+  type FilteringLogRecordProcessorConfig,
+} from './export/FilteringLogRecordProcessor';