feat: add per-job context to global Pino logger

Set jobId and roomName on the global logger when a job starts so that
all SDK-internal logs (TTS/STT metrics, speech events, AgentSession
lifecycle) are filterable by job in log aggregation tools.

Context is cleared after shutdown callbacks complete to prevent stale
fields leaking to the next job on the same worker.

Author: karan-dhir

.changeset/per-job-log-context.md

@@ -0,0 +1,9 @@
+---
+'@livekit/agents': minor
+---
+
+Add per-job context to the global Pino logger for session-level log filtering
+
+The global logger now automatically includes `jobId` and `roomName` on every log line during an active job. This makes it possible to filter all SDK-internal logs (TTS/STT metrics, speech events, AgentSession lifecycle) by job in log aggregation tools like NewRelic, Datadog, or Grafana.
+
+Context is set when a job starts and cleared after shutdown callbacks complete.

agents/src/ipc/job_proc_lazy_main.ts

@@ -8,6 +8,7 @@ import { pathToFileURL } from 'node:url';
 import type { Logger } from 'pino';
 import { type Agent, isAgent } from '../generator.js';
 import { JobContext, JobProcess, type RunningJobInfo, runWithJobContextAsync } from '../job.js';
+import { setJobContext } from '../log.js';
 import { initializeLogger, log } from '../log.js';
 import { Future, shortuuid } from '../utils.js';
 import { defaultInitializeProcessFunc } from '../worker.js';
@@ -184,6 +185,7 @@ const startJob = (
       logger.error({ error }, 'error while shutting down the job'),
     );
 
+    setJobContext({});
     safeSend({ case: 'done', value: undefined });
     joinFuture.resolve();
   })();

agents/src/job.ts

@@ -16,7 +16,7 @@ import * as os from 'node:os';
 import * as path from 'node:path';
 import type { Logger } from 'pino';
 import type { InferenceExecutor } from './ipc/inference_executor.js';
-import { log } from './log.js';
+import { log, setJobContext } from './log.js';
 import { flushOtelLogs, setupCloudTracer, uploadSessionReport } from './telemetry/index.js';
 import { isCloud } from './utils.js';
 import type { AgentSession } from './voice/agent_session.js';
@@ -139,10 +139,9 @@ export class JobContext<ProcessUserData = Record<string, unknown>> {
     this.#onShutdown = onShutdown;
     this.onParticipantConnected = this.onParticipantConnected.bind(this);
     this.#room.on(RoomEvent.ParticipantConnected, this.onParticipantConnected);
-    this.#logger = log().child({
-      jobId: this.#info.job.id,
-      roomName: this.#info.job.room?.name,
-    });
+    const jobCtx = { jobId: this.#info.job.id, roomName: this.#info.job.room?.name };
+    setJobContext(jobCtx);
+    this.#logger = log().child(jobCtx);
     this.#inferenceExecutor = inferenceExecutor;
     this._sessionDirectory = path.join(os.tmpdir(), 'livekit-agents', `job-${this.#info.job.id}`);
   }

agents/src/log.ts

@@ -17,11 +17,13 @@ export type LoggerOptions = {
 // This avoids the "dual package hazard". Symbol.for() returns the same Symbol
 // across all module instances, and globalThis is shared process-wide.
 const LOGGER_KEY = Symbol.for('@livekit/agents:logger');
+const BASE_LOGGER_KEY = Symbol.for('@livekit/agents:baseLogger');
 const LOGGER_OPTIONS_KEY = Symbol.for('@livekit/agents:loggerOptions');
 const OTEL_ENABLED_KEY = Symbol.for('@livekit/agents:otelEnabled');
 
 type GlobalState = {
   [LOGGER_KEY]?: Logger;
+  [BASE_LOGGER_KEY]?: Logger;
   [LOGGER_OPTIONS_KEY]?: LoggerOptions;
   [OTEL_ENABLED_KEY]?: boolean;
 };
@@ -40,6 +42,27 @@ export const log = () => {
   return logger;
 };
 
+/**
+ * Sets per-job context fields on the global logger. All subsequent calls to
+ * {@link log} will return a child logger that includes these fields on every
+ * log line (e.g. `jobId`, `roomName`).
+ *
+ * Call with an empty object to clear the context (e.g. after a job ends).
+ *
+ * @remarks
+ * LiveKit workers process one job at a time, so mutating the global logger
+ * is safe — there is no risk of concurrent jobs interleaving context.
+ *
+ * @internal
+ */
+export const setJobContext = (ctx: Record<string, unknown>) => {
+  if (!globals[BASE_LOGGER_KEY]) {
+    globals[BASE_LOGGER_KEY] = globals[LOGGER_KEY];
+  }
+  const base = globals[BASE_LOGGER_KEY]!;
+  globals[LOGGER_KEY] = Object.keys(ctx).length ? base.child(ctx) : base;
+};
+
 /** @internal */
 export const initializeLogger = ({ pretty, level }: LoggerOptions) => {
   globals[LOGGER_OPTIONS_KEY] = { pretty, level };
@@ -90,8 +113,10 @@ export const enableOtelLogging = () => {
     { stream: new OtelDestination(), level: 'debug' },
   ];
 
-  globals[LOGGER_KEY] = pino(
+  const newBase = pino(
     { level: logLevel, serializers: { error: pino.stdSerializers.err } },
     multistream(streams),
   );
+  globals[LOGGER_KEY] = newBase;
+  globals[BASE_LOGGER_KEY] = newBase;
 };