From f9222ce2337c0d037c2131e3c76d39a2a2c6a1ee Mon Sep 17 00:00:00 2001 From: User Date: Tue, 29 Sep 2026 11:13:55 +0200 Subject: [PATCH 1/2] #477 - Carry structured logging properties through worker hooks --- README.md | 9 + src/AppContext.ts | 1 + src/WorkerContext.ts | 49 +++- src/coreApi/coreApiLog.ts | 21 +- src/eventHandlers/InvocationHandler.ts | 5 +- src/hooks/LogHookContext.ts | 10 +- src/hooks/registerHook.ts | 15 +- src/setupCoreModule.ts | 1 + src/utils/structuredLogProperties.ts | 66 ++++++ test/eventHandlers/structuredLogging.test.ts | 226 +++++++++++++++++++ types-core/index.d.ts | 22 +- 11 files changed, 404 insertions(+), 21 deletions(-) create mode 100644 src/utils/structuredLogProperties.ts create mode 100644 test/eventHandlers/structuredLogging.test.ts diff --git a/README.md b/README.md index b0ee5b40..3d68643b 100644 --- a/README.md +++ b/README.md @@ -28,6 +28,15 @@ - Back in the worker repository, press F5 and select the process for your running function app - Before you submit a PR, run `npm run lint` and `npm test` and fix any issues. If you want to debug the tests, switch your [launch profile](https://code.visualstudio.com/docs/editor/debugging) in VS Code to "Launch Unit Tests" and press F5. +## Structured log metadata in the core API + +The built-in `@azure/functions-core` module exposes `supportsStructuredLogProperties` and accepts optional `{ attributes }` metadata as the fourth argument to `log`. The same argument is available on the invocation core context. Existing three-argument calls are unchanged. + +Attributes are copied into the process-local `LogHookContext.attributes` map. Only own enumerable string, boolean and finite-number values are accepted. Accessors, nested values and reserved telemetry keys are omitted without invoking getters or modifying the input. Reserved keys include `CategoryName`, `__proto__`, `prototype`, `constructor` and the prefixes `exception.`, `_MS`, `microsoft` and `ai.`, case-insensitively. + +A log exporter declares support with `registerHook("log", callback, { structuredLogProperties: true })` after it has been configured. Disposing the registration removes that declaration. A missing consumer or rejected metadata produces a system warning at most once per reason per invocation, or once per application outside an invocation. The original formatted message is still emitted once through the existing path. + +These attributes are not added to the worker-host RPC message. A compatible programming-model library and a direct telemetry exporter are required for queryable properties; this declaration does not guarantee network delivery or deduplication. ## Repositories These are the most important GitHub repositories that make up the Node.js experience on Azure Functions: diff --git a/src/AppContext.ts b/src/AppContext.ts index 09b3eb0b..fb7fa68f 100644 --- a/src/AppContext.ts +++ b/src/AppContext.ts @@ -34,6 +34,7 @@ export class AppContext { appStartHooks: HookCallback[] = []; appTerminateHooks: HookCallback[] = []; logHooks: HookCallback[] = []; + structuredLogHooks = new Set(); functions: { [id: string]: RegisteredFunction } = {}; legacyFunctions: { [id: string]: LegacyRegisteredFunction } = {}; workerIndexingLocked = false; diff --git a/src/WorkerContext.ts b/src/WorkerContext.ts index 46044fed..4065bed9 100644 --- a/src/WorkerContext.ts +++ b/src/WorkerContext.ts @@ -1,13 +1,14 @@ // Copyright (c) .NET Foundation. All rights reserved. // Licensed under the MIT License. -import { ProgrammingModel } from '@azure/functions-core'; +import { LogMetadata, ProgrammingModel } from '@azure/functions-core'; import { AzureFunctionsRpcMessages as rpc } from '../azure-functions-language-worker-protobuf/src/rpc'; import { AppContext } from './AppContext'; import { fromCoreLogLevel } from './coreApi/converters/fromCoreStatusResult'; import { AzFuncSystemError } from './errors'; import { IEventStream } from './GrpcClient'; import { InvocationLogContext, LogHookContext } from './hooks/LogHookContext'; +import { sanitizeLogMetadata } from './utils/structuredLogProperties'; class WorkerContext { app = new AppContext(undefined); @@ -18,6 +19,7 @@ class WorkerContext { */ _hostVersion?: string; + #structuredLogWarnings = new WeakMap>(); #id?: string; #eventStream?: IEventStream; #notInitializedMsg = 'WorkerContext has not been initialized yet.'; @@ -64,9 +66,23 @@ class WorkerContext { * @param requestId gRPC message request id * @param msg gRPC message content */ - log(log: rpc.IRpcLog, invocationLogCtx?: InvocationLogContext): void { + log(log: rpc.IRpcLog, invocationLogCtx?: InvocationLogContext, metadata?: LogMetadata): void { + const sanitized = sanitizeLogMetadata(metadata); + if (metadata !== undefined) { + if (sanitized.rejectedCount > 0) { + this.warnStructuredLog( + log, + invocationLogCtx, + 'structured_log_invalid_properties', + sanitized.rejectedCount + ); + } + if (!this.app.logHooks.some((callback) => this.app.structuredLogHooks.has(callback))) { + this.warnStructuredLog(log, invocationLogCtx, 'structured_log_consumer_unavailable'); + } + } try { - const logContext = new LogHookContext(log, invocationLogCtx); + const logContext = new LogHookContext(log, invocationLogCtx, sanitized.attributes); for (const callback of worker.app.logHooks) { callback(logContext); } @@ -85,6 +101,33 @@ class WorkerContext { rpcLog: log, }); } + private warnStructuredLog( + log: rpc.IRpcLog, + invocationLogCtx: InvocationLogContext | undefined, + reason: string, + rejectedCount?: number + ): void { + const scope = invocationLogCtx ?? this.app; + let warnings = this.#structuredLogWarnings.get(scope); + if (!warnings) { + warnings = new Set(); + this.#structuredLogWarnings.set(scope, warnings); + } + if (warnings.has(reason)) { + return; + } + warnings.add(reason); + this.log( + { + invocationId: log.invocationId, + category: log.category, + logCategory: rpc.RpcLog.RpcLogCategory.System, + level: rpc.RpcLog.Level.Warning, + message: rejectedCount === undefined ? reason : `${reason}: rejected ${rejectedCount} properties`, + }, + invocationLogCtx + ); + } } export const worker = new WorkerContext(); diff --git a/src/coreApi/coreApiLog.ts b/src/coreApi/coreApiLog.ts index 4e3b9e21..b5dd2807 100644 --- a/src/coreApi/coreApiLog.ts +++ b/src/coreApi/coreApiLog.ts @@ -5,10 +5,19 @@ import * as coreTypes from '@azure/functions-core'; import { worker } from '../WorkerContext'; import { fromCoreLogCategory, fromCoreLogLevel } from './converters/fromCoreStatusResult'; -export function coreApiLog(level: coreTypes.RpcLogLevel, category: coreTypes.RpcLogCategory, message: string): void { - worker.log({ - message, - level: fromCoreLogLevel(level), - logCategory: fromCoreLogCategory(category), - }); +export function coreApiLog( + level: coreTypes.RpcLogLevel, + category: coreTypes.RpcLogCategory, + message: string, + metadata?: coreTypes.LogMetadata +): void { + worker.log( + { + message, + level: fromCoreLogLevel(level), + logCategory: fromCoreLogCategory(category), + }, + undefined, + metadata + ); } diff --git a/src/eventHandlers/InvocationHandler.ts b/src/eventHandlers/InvocationHandler.ts index 9973dee4..37e167fd 100644 --- a/src/eventHandlers/InvocationHandler.ts +++ b/src/eventHandlers/InvocationHandler.ts @@ -169,7 +169,7 @@ class CoreInvocationContext implements coreTypes.CoreInvocationContext { this.#msgCategory = msgCategory; } - log(level: RpcLogLevel, logCategory: RpcLogCategory, message: string): void { + log(level: RpcLogLevel, logCategory: RpcLogCategory, message: string, metadata?: coreTypes.LogMetadata): void { worker.log( { invocationId: this.request.invocationId, @@ -178,7 +178,8 @@ class CoreInvocationContext implements coreTypes.CoreInvocationContext { level: fromCoreLogLevel(level), logCategory: fromCoreLogCategory(logCategory), }, - this.logContext + this.logContext, + metadata ); } } diff --git a/src/hooks/LogHookContext.ts b/src/hooks/LogHookContext.ts index cc56495c..9d6f7646 100644 --- a/src/hooks/LogHookContext.ts +++ b/src/hooks/LogHookContext.ts @@ -1,7 +1,7 @@ // Copyright (c) .NET Foundation. All rights reserved. // Licensed under the MIT License. -import { HookData, RpcLogCategory, RpcLogLevel } from '@azure/functions-core'; +import { HookData, LogAttributes, RpcLogCategory, RpcLogLevel } from '@azure/functions-core'; import * as coreTypes from '@azure/functions-core'; import { AzureFunctionsRpcMessages as rpc } from '../../azure-functions-language-worker-protobuf/src/rpc'; import { toCoreLog } from '../coreApi/converters/toCoreStatusResult'; @@ -18,10 +18,12 @@ export class LogHookContext implements coreTypes.LogHookContext { level: RpcLogLevel; message: string; #category: RpcLogCategory; + #attributes?: LogAttributes; #hookData: HookData; #invocationContext: unknown; - constructor(log: rpc.IRpcLog, invocLogCtx: InvocationLogContext | undefined) { + constructor(log: rpc.IRpcLog, invocLogCtx: InvocationLogContext | undefined, attributes?: LogAttributes) { + this.#attributes = attributes; const coreLog = toCoreLog(log); this.level = nonNullProp(coreLog, 'level'); this.message = nonNullProp(coreLog, 'message'); @@ -30,6 +32,10 @@ export class LogHookContext implements coreTypes.LogHookContext { this.#invocationContext = invocLogCtx?.invocationContext; } + get attributes(): LogAttributes | undefined { + return this.#attributes; + } + get hookData(): HookData { return this.#hookData; } diff --git a/src/hooks/registerHook.ts b/src/hooks/registerHook.ts index e2e192da..ea8e6f4d 100644 --- a/src/hooks/registerHook.ts +++ b/src/hooks/registerHook.ts @@ -1,15 +1,22 @@ // Copyright (c) .NET Foundation. All rights reserved. // Licensed under the MIT License. -import { HookCallback } from '@azure/functions-core'; +import { HookCallback, LogHookOptions } from '@azure/functions-core'; import { Disposable } from '../Disposable'; +import { worker } from '../WorkerContext'; import { getHooks } from './getHooks'; -export function registerHook(hookName: string, callback: HookCallback): Disposable { +export function registerHook(hookName: string, callback: HookCallback, options?: LogHookOptions): Disposable { const hooks = getHooks(hookName); - hooks.push(callback); + const app = worker.app; + const registeredCallback: HookCallback = (context) => callback(context); + hooks.push(registeredCallback); + if (hookName === 'log' && options?.structuredLogProperties === true) { + app.structuredLogHooks.add(registeredCallback); + } return new Disposable(() => { - const index = hooks.indexOf(callback); + app.structuredLogHooks.delete(registeredCallback); + const index = hooks.indexOf(registeredCallback); if (index > -1) { hooks.splice(index, 1); } diff --git a/src/setupCoreModule.ts b/src/setupCoreModule.ts index 67e409bf..b8e6760c 100644 --- a/src/setupCoreModule.ts +++ b/src/setupCoreModule.ts @@ -18,6 +18,7 @@ import Module = require('module'); export function setupCoreModule(): void { const coreApi = { version: version, + supportsStructuredLogProperties: true, get hostVersion() { return worker.hostVersion; }, diff --git a/src/utils/structuredLogProperties.ts b/src/utils/structuredLogProperties.ts new file mode 100644 index 00000000..33c65093 --- /dev/null +++ b/src/utils/structuredLogProperties.ts @@ -0,0 +1,66 @@ +// Copyright (c) .NET Foundation. All rights reserved. +// Licensed under the MIT License. + +import { LogAttributes } from '@azure/functions-core'; + +export function sanitizeLogMetadata(metadata: unknown): { attributes?: LogAttributes; rejectedCount: number } { + if (metadata === undefined) { + return { rejectedCount: 0 }; + } + const attributes: Record = Object.create(null); + let rejectedCount = 0; + try { + if (typeof metadata !== 'object' || metadata === null) { + return { attributes: Object.freeze(attributes), rejectedCount: 1 }; + } + const attributesDescriptor = Object.getOwnPropertyDescriptor(metadata, 'attributes'); + const suppliedAttributes: unknown = attributesDescriptor?.value; + if (typeof suppliedAttributes !== 'object' || suppliedAttributes === null) { + return { attributes: Object.freeze(attributes), rejectedCount: 1 }; + } + const prototype: unknown = Object.getPrototypeOf(suppliedAttributes); + if (prototype !== Object.prototype && prototype !== null) { + return { attributes: Object.freeze(attributes), rejectedCount: 1 }; + } + const descriptors = Object.getOwnPropertyDescriptors(suppliedAttributes); + for (const property of Reflect.ownKeys(descriptors)) { + const descriptor = Object.getOwnPropertyDescriptor(descriptors, property)?.value as PropertyDescriptor; + if (!descriptor.enumerable) { + continue; + } + const attributeValue: unknown = descriptor.value; + if ( + typeof property !== 'string' || + isReservedProperty(property) || + !('value' in descriptor) || + !isAttributeValue(attributeValue) + ) { + rejectedCount++; + continue; + } + attributes[property] = attributeValue; + } + } catch { + rejectedCount++; + } + return { attributes: Object.freeze(attributes), rejectedCount }; +} + +function isReservedProperty(property: string): boolean { + const normalized = property.toLowerCase(); + return ( + normalized === 'categoryname' || + normalized === '__proto__' || + normalized === 'prototype' || + normalized === 'constructor' || + ['exception.', '_ms', 'microsoft', 'ai.'].some((prefix) => normalized.startsWith(prefix)) + ); +} + +function isAttributeValue(attributeValue: unknown): attributeValue is string | number | boolean { + return ( + typeof attributeValue === 'string' || + typeof attributeValue === 'boolean' || + (typeof attributeValue === 'number' && Number.isFinite(attributeValue)) + ); +} diff --git a/test/eventHandlers/structuredLogging.test.ts b/test/eventHandlers/structuredLogging.test.ts new file mode 100644 index 00000000..e7ecf7cf --- /dev/null +++ b/test/eventHandlers/structuredLogging.test.ts @@ -0,0 +1,226 @@ +// Copyright (c) .NET Foundation. All rights reserved. +// Licensed under the MIT License. + +import 'mocha'; +import * as coreTypes from '@azure/functions-core'; +import { expect } from 'chai'; +import { AzureFunctionsRpcMessages as rpc } from '../../azure-functions-language-worker-protobuf/src/rpc'; +import { InvocationHandler } from '../../src/eventHandlers/InvocationHandler'; +import { InvocationLogContext } from '../../src/hooks/LogHookContext'; +import { worker } from '../../src/WorkerContext'; +import { beforeEventHandlerSuite } from './beforeEventHandlerSuite'; +import { TestEventStream } from './TestEventStream'; + +describe('structured log properties', () => { + let stream: TestEventStream; + let coreApi: typeof coreTypes; + + before(async () => { + stream = beforeEventHandlerSuite(); + coreApi = await import('@azure/functions-core'); + }); + + afterEach(async () => { + stream.written.resetHistory(); + await stream.afterEachEventHandlerTest(); + }); + + function logs(): rpc.IRpcLog[] { + return stream.written.getCalls().map((call) => (call.args[0] as rpc.IStreamingMessage).rpcLog!); + } + + function logWithMetadata(attributes: unknown, context?: InvocationLogContext): void { + worker.log( + { + message: 'submission failed { stationId: Merida }', + level: rpc.RpcLog.Level.Error, + logCategory: rpc.RpcLog.RpcLogCategory.User, + invocationId: 'invocation-one', + }, + context, + { attributes } as coreTypes.LogMetadata + ); + } + + it('exposes capability and preserves metadata only on the process-local hook path', () => { + expect(coreApi.supportsStructuredLogProperties).to.equal(true); + const captured: coreTypes.LogHookContext[] = []; + coreApi.registerHook('log', (context) => captured.push(context), { structuredLogProperties: true }); + coreApi.log('error', 'user', 'submission failed', { + attributes: { stationId: 'Merida', attempts: 2, retry: false }, + }); + expect(captured).to.have.length(1); + expect(captured[0].attributes).to.deep.equal({ stationId: 'Merida', attempts: 2, retry: false }); + expect(Object.isFrozen(captured[0].attributes)).to.equal(true); + expect(logs()).to.deep.equal([ + { + message: 'submission failed', + level: rpc.RpcLog.Level.Error, + logCategory: rpc.RpcLog.RpcLogCategory.User, + }, + ]); + const roundTrip = rpc.StreamingMessage.decode(rpc.StreamingMessage.encode({ rpcLog: logs()[0] }).finish()); + expect(roundTrip.rpcLog?.message).to.equal('submission failed'); + expect(Object.keys(roundTrip.rpcLog?.propertiesMap ?? {})).to.have.length(0); + }); + + it('retains one original log per call and bounds missing-consumer warnings by invocation', () => { + const first = { hookData: {}, invocationContext: { invocationId: 'first' } }; + const second = { hookData: {}, invocationContext: { invocationId: 'second' } }; + const observed: string[] = []; + coreApi.registerHook('log', (context) => observed.push(context.message)); + logWithMetadata({ stationId: 'Merida' }, first); + logWithMetadata({ stationId: 'Merida' }, first); + logWithMetadata({ stationId: 'Other' }, second); + expect(logs().filter((log) => log.logCategory === rpc.RpcLog.RpcLogCategory.User)).to.have.length(3); + expect(logs().filter((log) => log.message === 'structured_log_consumer_unavailable')).to.have.length(2); + expect(observed).to.have.length(5); + }); + + it('removes consumer support on disposal, including duplicate registrations', () => { + const callback = () => {}; + const first = coreApi.registerHook('log', callback, { structuredLogProperties: true }); + const second = coreApi.registerHook('log', callback, { structuredLogProperties: true }); + first.dispose(); + coreApi.log('information', 'user', 'first', { attributes: {} }); + expect(logs()).to.have.length(1); + second.dispose(); + coreApi.log('information', 'user', 'second', { attributes: {} }); + coreApi.log('information', 'user', 'third', { attributes: {} }); + expect(logs().filter((log) => log.message === 'structured_log_consumer_unavailable')).to.have.length(1); + expect(logs().filter((log) => log.logCategory === rpc.RpcLog.RpcLogCategory.User)).to.have.length(3); + }); + + it('does not call getters, mutate inputs or export invalid and reserved attributes', () => { + const attributes: Record = { + stationId: 'Merida', + zero: 0, + enabled: false, + nan: NaN, + infinity: Infinity, + negativeInfinity: -Infinity, + missing: undefined, + nil: null, + bigint: BigInt(7), + nested: {}, + array: [], + date: new Date(), + error: new Error('secret'), + callback: () => {}, + symbol: Symbol('secret'), + CategoryName: 'secret', + 'EXCEPTION.Type': 'secret', + 'exception.stacktrace': 'secret', + '_MS.secret': 'secret', + microsoftSecret: 'secret', + 'AI.operation.id': 'secret', + constructor: 'secret', + prototype: 'secret', + }; + Object.defineProperty(attributes, '__proto__', { value: 'secret', enumerable: true }); + let getterCalls = 0; + Object.defineProperty(attributes, 'getter', { + enumerable: true, + get: () => { + getterCalls++; + throw new Error('secret'); + }, + }); + const captured: coreTypes.LogHookContext[] = []; + coreApi.registerHook('log', (context) => captured.push(context), { structuredLogProperties: true }); + logWithMetadata(attributes); + expect(getterCalls).to.equal(0); + expect(attributes.stationId).to.equal('Merida'); + expect(attributes.CategoryName).to.equal('secret'); + const userLog = captured.find((context) => context.category === 'user')!; + expect(userLog.attributes).to.deep.equal({ stationId: 'Merida', zero: 0, enabled: false }); + const warning = logs().find((log) => log.level === rpc.RpcLog.Level.Warning)!; + expect(warning.message).to.contain('structured_log_invalid_properties'); + expect(warning.message).not.to.contain('secret'); + expect(logs().filter((log) => log.logCategory === rpc.RpcLog.RpcLogCategory.User)).to.have.length(1); + }); + + it('contains failures from hostile metadata and property maps', () => { + coreApi.registerHook('log', () => {}, { structuredLogProperties: true }); + const hostile = new Proxy( + {}, + { + ownKeys: () => { + throw new Error('secret'); + }, + } + ); + expect(() => logWithMetadata(hostile)).not.to.throw(); + const metadata = Object.defineProperty({}, 'attributes', { + get: () => { + throw new Error('secret'); + }, + }); + expect(() => coreApi.log('error', 'user', 'original', metadata as coreTypes.LogMetadata)).not.to.throw(); + expect(logs().filter((log) => log.logCategory === rpc.RpcLog.RpcLogCategory.User)).to.have.length(2); + expect(logs().filter((log) => log.level === rpc.RpcLog.Level.Warning)).to.have.length(1); + }); + + it('preserves legacy hook mutation and hook-error behavior', () => { + coreApi.registerHook('log', (context) => { + context.message += ' changed'; + context.level = 'warning'; + }); + coreApi.log('information', 'user', 'legacy'); + expect(logs()[0].message).to.equal('legacy changed'); + expect(logs()[0].level).to.equal(rpc.RpcLog.Level.Warning); + coreApi.registerHook( + 'log', + () => { + throw new Error('hook failure'); + }, + { structuredLogProperties: true } + ); + expect(() => coreApi.log('error', 'user', 'original', { attributes: { stationId: 'Merida' } })).not.to.throw(); + expect(logs()[1].message).to.equal('original'); + expect(logs()[1].level).to.equal(rpc.RpcLog.Level.Error); + }); + + it('carries attributes and invocation context through real concurrent invocation handlers', async () => { + const captured: coreTypes.LogHookContext[] = []; + coreApi.registerHook( + 'log', + (context) => { + if (context.category === 'user') captured.push(context); + }, + { structuredLogProperties: true } + ); + worker.app.isUsingWorkerIndexing = true; + worker.app.functions.station = { metadata: { name: 'station' }, callback: () => {} }; + worker.app.programmingModel = { + name: 'structured logging test', + version: '1', + getInvocationModel: (coreContext) => ({ + getArguments: async () => ({ context: { invocationId: coreContext.invocationId }, inputs: [] }), + invokeFunction: async () => { + await Promise.resolve(); + coreContext.log('error', 'user', `failure ${coreContext.invocationId}`, { + attributes: { stationId: coreContext.invocationId }, + }); + }, + getResponse: async () => ({ invocationId: coreContext.invocationId }), + }), + }; + await Promise.all( + ['Merida', 'Other'].map((invocationId) => + new InvocationHandler().handleEvent({ invocationId, functionId: 'station' }) + ) + ); + expect(captured).to.have.length(2); + for (const context of captured) { + const invocationId = (context.invocationContext as { invocationId: string }).invocationId; + expect(context.attributes).to.deep.equal({ stationId: invocationId }); + expect(context.message).to.equal(`failure ${invocationId}`); + } + expect( + logs() + .filter((log) => log.logCategory === rpc.RpcLog.RpcLogCategory.User) + .map((log) => log.invocationId) + ).to.have.members(['Merida', 'Other']); + }); +}); diff --git a/types-core/index.d.ts b/types-core/index.d.ts index 2fb35060..758775ea 100644 --- a/types-core/index.d.ts +++ b/types-core/index.d.ts @@ -10,6 +10,8 @@ declare module '@azure/functions-core' { */ const version: string; + const supportsStructuredLogProperties: boolean | undefined; + /** * The version of the Functions Host */ @@ -58,8 +60,18 @@ declare module '@azure/functions-core' { function registerHook(hookName: 'postInvocation', callback: PostInvocationCallback): Disposable; function registerHook(hookName: 'appStart', callback: AppStartCallback): Disposable; function registerHook(hookName: 'appTerminate', callback: AppTerminateCallback): Disposable; - function registerHook(hookName: 'log', callback: LogHookCallback): Disposable; - function registerHook(hookName: string, callback: HookCallback): Disposable; + function registerHook(hookName: 'log', callback: LogHookCallback, options?: LogHookOptions): Disposable; + function registerHook(hookName: string, callback: HookCallback, options?: LogHookOptions): Disposable; + + interface LogHookOptions { + structuredLogProperties?: boolean; + } + + type LogAttributes = Readonly>; + + interface LogMetadata { + readonly attributes: LogAttributes; + } type HookCallback = (context: HookContext) => unknown; type PreInvocationCallback = (context: PreInvocationContext) => void | Promise; @@ -149,6 +161,8 @@ declare module '@azure/functions-core' { type AppTerminateContext = HookContext; interface LogHookContext extends HookContext { + readonly attributes?: LogAttributes; + /** * If the log occurs during a function execution, the context object passed to the function handler. * Otherwise, undefined. @@ -214,7 +228,7 @@ declare module '@azure/functions-core' { * The recommended way to log information outside the context of an invocation * During an invocation, use `CoreInvocationContext.log` instead */ - function log(level: RpcLogLevel, category: RpcLogCategory, message: string): void; + function log(level: RpcLogLevel, category: RpcLogCategory, message: string, metadata?: LogMetadata): void; /** * A set of information and methods that describe the model for handling a Node.js function app @@ -271,7 +285,7 @@ declare module '@azure/functions-core' { /** * The recommended way to log information */ - log(level: RpcLogLevel, category: RpcLogCategory, message: string): void; + log(level: RpcLogLevel, category: RpcLogCategory, message: string, metadata?: LogMetadata): void; } type InvocationState = 'preInvocationHooks' | 'postInvocationHooks' | 'invocation'; From a6ddd3ac151dcc7d6cbc0955b75c90820b9afb56 Mon Sep 17 00:00:00 2001 From: User Date: Tue, 29 Sep 2026 11:41:53 +0200 Subject: [PATCH 2/2] #477 - Isolate structured log warnings throughout invocation setup --- src/WorkerContext.ts | 12 +++-- src/eventHandlers/InvocationHandler.ts | 3 +- test/eventHandlers/structuredLogging.test.ts | 48 ++++++++++++++++++++ types-core/index.d.ts | 2 +- 4 files changed, 60 insertions(+), 5 deletions(-) diff --git a/src/WorkerContext.ts b/src/WorkerContext.ts index 4065bed9..c6828d3f 100644 --- a/src/WorkerContext.ts +++ b/src/WorkerContext.ts @@ -66,19 +66,25 @@ class WorkerContext { * @param requestId gRPC message request id * @param msg gRPC message content */ - log(log: rpc.IRpcLog, invocationLogCtx?: InvocationLogContext, metadata?: LogMetadata): void { + log( + log: rpc.IRpcLog, + invocationLogCtx?: InvocationLogContext, + metadata?: LogMetadata, + warningScope: object = invocationLogCtx ?? this.app + ): void { const sanitized = sanitizeLogMetadata(metadata); if (metadata !== undefined) { if (sanitized.rejectedCount > 0) { this.warnStructuredLog( log, invocationLogCtx, + warningScope, 'structured_log_invalid_properties', sanitized.rejectedCount ); } if (!this.app.logHooks.some((callback) => this.app.structuredLogHooks.has(callback))) { - this.warnStructuredLog(log, invocationLogCtx, 'structured_log_consumer_unavailable'); + this.warnStructuredLog(log, invocationLogCtx, warningScope, 'structured_log_consumer_unavailable'); } } try { @@ -104,10 +110,10 @@ class WorkerContext { private warnStructuredLog( log: rpc.IRpcLog, invocationLogCtx: InvocationLogContext | undefined, + scope: object, reason: string, rejectedCount?: number ): void { - const scope = invocationLogCtx ?? this.app; let warnings = this.#structuredLogWarnings.get(scope); if (!warnings) { warnings = new Set(); diff --git a/src/eventHandlers/InvocationHandler.ts b/src/eventHandlers/InvocationHandler.ts index 37e167fd..2f174c62 100644 --- a/src/eventHandlers/InvocationHandler.ts +++ b/src/eventHandlers/InvocationHandler.ts @@ -179,7 +179,8 @@ class CoreInvocationContext implements coreTypes.CoreInvocationContext { logCategory: fromCoreLogCategory(logCategory), }, this.logContext, - metadata + metadata, + this ); } } diff --git a/test/eventHandlers/structuredLogging.test.ts b/test/eventHandlers/structuredLogging.test.ts index e7ecf7cf..6003c07b 100644 --- a/test/eventHandlers/structuredLogging.test.ts +++ b/test/eventHandlers/structuredLogging.test.ts @@ -42,6 +42,14 @@ describe('structured log properties', () => { ); } + it('restricts structured logging options to log hooks in the public types', () => { + const checkTypes = () => { + // @ts-expect-error Log options do not apply to invocation hooks. + coreApi.registerHook('preInvocation', () => {}, { structuredLogProperties: true }); + }; + void checkTypes; + }); + it('exposes capability and preserves metadata only on the process-local hook path', () => { expect(coreApi.supportsStructuredLogProperties).to.equal(true); const captured: coreTypes.LogHookContext[] = []; @@ -181,6 +189,46 @@ describe('structured log properties', () => { expect(logs()[1].level).to.equal(rpc.RpcLog.Level.Error); }); + it('isolates warnings across invocation preparation and execution', async () => { + worker.app.isUsingWorkerIndexing = true; + worker.app.functions.example = { metadata: { name: 'example' }, callback: () => {} }; + worker.app.programmingModel = { + name: 'early logging test', + version: '1', + getInvocationModel: (coreContext) => { + const emit = () => coreContext.log('error', 'user', 'failure', { attributes: { invalid: NaN } }); + emit(); + return { + getArguments: async () => { + emit(); + return { context: { invocationId: coreContext.invocationId }, inputs: [] }; + }, + invokeFunction: async () => { + emit(); + }, + getResponse: async () => ({ invocationId: coreContext.invocationId }), + }; + }, + }; + await Promise.all( + ['first', 'second'].map((invocationId) => + new InvocationHandler().handleEvent({ invocationId, functionId: 'example' }) + ) + ); + for (const invocationId of ['first', 'second']) { + const invocationLogs = logs().filter((log) => log.invocationId === invocationId); + expect( + invocationLogs.filter((log) => log.message === 'structured_log_consumer_unavailable') + ).to.have.length(1); + expect( + invocationLogs.filter((log) => log.message?.startsWith('structured_log_invalid_properties')) + ).to.have.length(1); + expect(invocationLogs.filter((log) => log.logCategory === rpc.RpcLog.RpcLogCategory.User)).to.have.length( + 3 + ); + } + }); + it('carries attributes and invocation context through real concurrent invocation handlers', async () => { const captured: coreTypes.LogHookContext[] = []; coreApi.registerHook( diff --git a/types-core/index.d.ts b/types-core/index.d.ts index 758775ea..34c22697 100644 --- a/types-core/index.d.ts +++ b/types-core/index.d.ts @@ -61,7 +61,7 @@ declare module '@azure/functions-core' { function registerHook(hookName: 'appStart', callback: AppStartCallback): Disposable; function registerHook(hookName: 'appTerminate', callback: AppTerminateCallback): Disposable; function registerHook(hookName: 'log', callback: LogHookCallback, options?: LogHookOptions): Disposable; - function registerHook(hookName: string, callback: HookCallback, options?: LogHookOptions): Disposable; + function registerHook(hookName: string, callback: HookCallback): Disposable; interface LogHookOptions { structuredLogProperties?: boolean;