feat(log-capture): pino integration and public API

Adds log-capture support to the pino plugin. When logCaptureEnabled is
true, the write hook publishes each serialized JSON log line to the
apm:pino:log:json diagnostic channel so the log-capture sender can
forward them to the Datadog log intake without requiring a sidecar Agent.

The hook is designed as an additive path alongside the existing log
injection: log injection (dd.trace_id / dd.span_id correlation) still
works independently, and capture-only mode (logInjection: false,
logCaptureEnabled: true) leaves the log record unmodified.

- pino/src/index.js: publish complete JSON line to apm:pino:log:json
  on every write when logCaptureEnabled; compatible with pino 5-8.
  Pass hasUserDd so the plugin skips injection but still captures records
  that already carry a caller-provided dd field.
- datadog-instrumentations/src/pino.js: always publish to channel when
  subscribers exist; hasUserDd flag prevents injection from overwriting
  a caller-owned dd field while still forwarding the record for capture.
- docs/API.md: public documentation for DD_LOG_CAPTURE_* options
- .github/workflows/instrumentation.yml: add pino to instrumentation CI
- pino/test/unit.spec.js: unit test for capture-only mode
- pino/test/index.spec.js: integration smoke test for the JSON channel

Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

Author: litianningdatadog

.github/workflows/instrumentation.yml

@@ -464,6 +464,16 @@ jobs:
       - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
       - uses: ./.github/actions/instrumentations/test
 
+  instrumentation-pino:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    env:
+      PLUGINS: pino
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+      - uses: ./.github/actions/instrumentations/test
+
   instrumentation-promise-js:
     runs-on: ubuntu-latest
     permissions:

docs/API.md

@@ -535,6 +535,38 @@ const tracer = require('dd-trace').init({
 })
 ```
 
+<h4 id="log-capture">Automatic log capture</h4>
+
+dd-trace can forward JSON log records written by Pino directly to a custom HTTP(S) intake without adding transports to each logger. The forwarding hook publishes full log entries (including Datadog trace metadata when log injection is enabled) through an internal buffer that flushes on a timer and before process exit.
+
+**Default behavior:** Log capture is enabled automatically in certain environments. For all other environments, enable it with `logCaptureEnabled: true` (or `DD_LOG_CAPTURE_ENABLED=true`). By default the sender targets `localhost:10517`; override with `logCaptureHost`/`DD_LOG_CAPTURE_HOST` and `logCapturePort`/`DD_LOG_CAPTURE_PORT` when needed.
+
+Optional tuning knobs map 1:1 with the configuration API:
+
+* `logCaptureHost` (`DD_LOG_CAPTURE_HOST`, default `localhost`)
+* `logCapturePort` (`DD_LOG_CAPTURE_PORT`, default `10517`)
+* `logCapturePath` (`DD_LOG_CAPTURE_PATH`, default `/logs`)
+* `logCaptureProtocol` (`DD_LOG_CAPTURE_PROTOCOL`, default `http:`)
+* `logCaptureMaxBufferSize` (`DD_LOG_CAPTURE_MAX_BUFFER_SIZE`, default `1000` records)
+* `logCaptureFlushIntervalMs` (`DD_LOG_CAPTURE_FLUSH_INTERVAL_MS`, default `5000`)
+* `logCaptureTimeoutMs` (`DD_LOG_CAPTURE_TIMEOUT_MS`, default `5000`)
+
+Example:
+
+```javascript
+require('dd-trace').init({
+  logInjection: true,
+  logCaptureEnabled: true,
+  // host and port default to localhost:10517; override if needed:
+  logCaptureHost: 'logs.my-intake.internal',
+  logCapturePort: 8080,
+  logCaptureProtocol: 'https:',
+})
+```
+
+No additional transports or stream shims are required in user code.
+
+
 <h3 id="span-hooks">Span Hooks</h3>
 
 In some cases, it's necessary to update the metadata of a span created by one of the built-in integrations. This is possible using span hooks registered by integration. Each hook provides the span as the first argument and other contextual objects as additional arguments.

packages/datadog-instrumentations/src/pino.js

@@ -35,12 +35,12 @@ function wrapAsJson (asJson) {
   return function asJsonWithTrace (obj, msg, num, time) {
     obj = arguments[0] = obj || {}
 
-    // Caller-provided `dd` wins -- skip the splice so a bespoke `dd` survives.
-    if (!jsonCh.hasSubscribers || Object.hasOwn(obj, 'dd')) {
+    if (!jsonCh.hasSubscribers) {
       return asJson.apply(this, arguments)
     }
 
-    const payload = { line: asJson.apply(this, arguments) }
+    // Pass hasUserDd so the plugin can skip injection while still capturing.
+    const payload = { line: asJson.apply(this, arguments), hasUserDd: Object.hasOwn(obj, 'dd') }
     jsonCh.publish(payload)
     return payload.line
   }

packages/datadog-plugin-pino/src/index.js

@@ -13,23 +13,62 @@ class PinoPlugin extends LogPlugin {
   }
 
   /**
-   * Splice `,"dd":<json>` into the JSON line pino has already produced.
+   * Disable the generic apm:${id}:log capture path for pino.
+   *
+   * Pino's apm:pino:log:json channel provides the fully-serialized JSON line
+   * and is used for both injection and capture in handleJsonLine.
+   * This prevents double-capture from the LogPlugin base class subscriber.
+   *
+   * @returns {false}
+   */
+  get _captureEnabled () {
+    return false
+  }
+
+  /**
+   * Splice `,"dd":<json>` into the JSON line pino has already produced,
+   * and optionally capture the complete record for log forwarding.
    * The caller-owned message object is never observed -- user Proxies and
    * custom serialisers see nothing because there is no mutation to see.
    *
    * @param {{ line: string }} payload
    */
   handleJsonLine (payload) {
+    if (typeof payload?.line !== 'string') return
+
+    // hasUserDd: caller already has a dd field — preserve it; skip injection but still capture.
+    const shouldInject = this.config.logInjection && !payload.hasUserDd
+    const shouldCapture = this.config.logCaptureEnabled
+
+    if (!shouldInject && !shouldCapture) return
+
     const logHolder = buildLogHolder(this.tracer)
-    if (!logHolder) return
 
-    const line = payload.line
-    const lastClose = line.lastIndexOf('}')
-    if (lastClose < 1) return
+    if (shouldInject && logHolder) {
+      const line = payload.line
+      const lastClose = line.lastIndexOf('}')
+      if (lastClose >= 1) {
+        const ddJson = JSON.stringify(logHolder.dd)
+        const sep = line.charCodeAt(lastClose - 1) === 0x7B ? '' : ','
+        payload.line = line.slice(0, lastClose) + sep + '"dd":' + ddJson + line.slice(lastClose)
+      }
+    }
 
-    const ddJson = JSON.stringify(logHolder.dd)
-    const sep = line.charCodeAt(lastClose - 1) === 0x7B ? '' : ','
-    payload.line = line.slice(0, lastClose) + sep + '"dd":' + ddJson + line.slice(lastClose)
+    if (shouldCapture) {
+      if (!shouldInject && logHolder) {
+        // Enrich the captured record with dd context without modifying the actual log line.
+        const line = payload.line
+        const lastClose = line.lastIndexOf('}')
+        if (lastClose >= 1) {
+          const ddJson = JSON.stringify(logHolder.dd)
+          const sep = line.charCodeAt(lastClose - 1) === 0x7B ? '' : ','
+          this.capture(line.slice(0, lastClose) + sep + '"dd":' + ddJson + line.slice(lastClose))
+          return
+        }
+      }
+      // If injection already happened, payload.line includes dd; otherwise capture raw.
+      this.capture(payload.line)
+    }
   }
 
   /**
@@ -41,6 +80,8 @@ class PinoPlugin extends LogPlugin {
    * @param {{ message: object }} arg
    */
   handlePrettyMessage (arg) {
+    if (!this.config.logInjection) return
+
     const logHolder = buildLogHolder(this.tracer)
     if (!logHolder) return
 

packages/datadog-plugin-pino/test/index.spec.js

@@ -47,6 +47,16 @@ describe('Plugin', () => {
             const pretty = require('../../../versions/pino-pretty@8.0.0').get()
 
             stream = pretty().pipe(stream)
+          } else if (semver.intersects(version, '>=5 <8') && options.prettyPrint) {
+            // pino 5-7 supports prettyPrint internally by calling require('pino-pretty').
+            // In this test environment, that resolves to pino-pretty@8 which exports an
+            // abstractTransport-based Transform stream — incompatible with pino 5-7's
+            // expectation of a sync factory function. pino-pretty@8 also creates a
+            // SonicBoom (writing to stdout) that registers with on-exit-leak-free,
+            // leaving async resources that prevent mocha from exiting after the test.
+            // Provide pino-pretty@3 via the `prettifier` option so pino uses its
+            // synchronous factory interface and avoids the leaked resources.
+            options.prettifier = require('../../../versions/pino-pretty@3.0.0').get()
           }
 
           logger = pino(options, stream)
@@ -247,6 +257,41 @@ describe('Plugin', () => {
             })
           }
         })
+
+        describe('log capture channel (apm:pino:log:json)', () => {
+          beforeEach(() => {
+            return agent.load('pino')
+          })
+
+          beforeEach(function () {
+            setupTest()
+
+            if (!logger) {
+              this.skip()
+            }
+          })
+
+          it('should emit a complete JSON record including pid, hostname, level, time, msg', (done) => {
+            const { channel } = require('dc-polyfill')
+            const captureCh = channel('apm:pino:log:json')
+            let captured
+            const sub = (payload) => { captured = payload }
+            captureCh.subscribe(sub)
+
+            logger.info('hello capture')
+
+            setImmediate(() => {
+              captureCh.unsubscribe(sub)
+              assert.ok(captured, 'json channel should have fired')
+              const record = JSON.parse(captured.line)
+              assert.ok(record.pid, 'should have pid')
+              assert.ok(record.hostname, 'should have hostname')
+              assert.ok(record.time, 'should have time')
+              assert.strictEqual(record.msg, 'hello capture')
+              done()
+            })
+          })
+        })
       })
     })
   })

packages/datadog-plugin-pino/test/unit.spec.js

@@ -132,5 +132,18 @@ describe('PinoPlugin', () => {
         tracer.inject = originalInject
       }
     })
+
+    it('leaves the message untouched when logInjection is disabled (capture-only mode)', () => {
+      plugin.configure({ logInjection: false, logCaptureEnabled: true, enabled: true })
+      try {
+        const original = { msg: 'hello', level: 30 }
+        const data = { message: original }
+        messageCh.publish(data)
+        assert.strictEqual(data.message, original, 'message should not be wrapped in capture-only mode')
+        assert.ok(!('dd' in data.message), 'dd should not be injected when logInjection is false')
+      } finally {
+        plugin.configure({ logInjection: true, enabled: true })
+      }
+    })
   })
 })