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..c6828d3f 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,29 @@ 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,
+ 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, warningScope, '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 +107,33 @@ class WorkerContext {
rpcLog: log,
});
}
+ private warnStructuredLog(
+ log: rpc.IRpcLog,
+ invocationLogCtx: InvocationLogContext | undefined,
+ scope: object,
+ reason: string,
+ rejectedCount?: number
+ ): void {
+ 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..2f174c62 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,9 @@ class CoreInvocationContext implements coreTypes.CoreInvocationContext {
level: fromCoreLogLevel(level),
logCategory: fromCoreLogCategory(logCategory),
},
- this.logContext
+ this.logContext,
+ metadata,
+ this
);
}
}
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..6003c07b
--- /dev/null
+++ b/test/eventHandlers/structuredLogging.test.ts
@@ -0,0 +1,274 @@
+// 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('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[] = [];
+ 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('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(
+ '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..34c22697 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,9 +60,19 @@ 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: 'log', callback: LogHookCallback, options?: LogHookOptions): Disposable;
function registerHook(hookName: string, callback: HookCallback): Disposable;
+ interface LogHookOptions {
+ structuredLogProperties?: boolean;
+ }
+
+ type LogAttributes = Readonly>;
+
+ interface LogMetadata {
+ readonly attributes: LogAttributes;
+ }
+
type HookCallback = (context: HookContext) => unknown;
type PreInvocationCallback = (context: PreInvocationContext) => void | Promise;
type PostInvocationCallback = (context: PostInvocationContext) => 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';