Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,15 @@
- Back in the worker repository, press <kbd>F5</kbd> 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 <kbd>F5</kbd>.

## 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:
Expand Down
1 change: 1 addition & 0 deletions src/AppContext.ts
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,7 @@ export class AppContext {
appStartHooks: HookCallback[] = [];
appTerminateHooks: HookCallback[] = [];
logHooks: HookCallback[] = [];
structuredLogHooks = new Set<HookCallback>();
functions: { [id: string]: RegisteredFunction } = {};
legacyFunctions: { [id: string]: LegacyRegisteredFunction } = {};
workerIndexingLocked = false;
Expand Down
55 changes: 52 additions & 3 deletions src/WorkerContext.ts
Original file line number Diff line number Diff line change
@@ -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);
Expand All @@ -18,6 +19,7 @@ class WorkerContext {
*/
_hostVersion?: string;

#structuredLogWarnings = new WeakMap<object, Set<string>>();
#id?: string;
#eventStream?: IEventStream;
#notInitializedMsg = 'WorkerContext has not been initialized yet.';
Expand Down Expand Up @@ -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);
}
Expand All @@ -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<string>();
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();
21 changes: 15 additions & 6 deletions src/coreApi/coreApiLog.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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
);
}
6 changes: 4 additions & 2 deletions src/eventHandlers/InvocationHandler.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand All @@ -178,7 +178,9 @@ class CoreInvocationContext implements coreTypes.CoreInvocationContext {
level: fromCoreLogLevel(level),
logCategory: fromCoreLogCategory(logCategory),
},
this.logContext
this.logContext,
metadata,
this
);
}
}
10 changes: 8 additions & 2 deletions src/hooks/LogHookContext.ts
Original file line number Diff line number Diff line change
@@ -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';
Expand All @@ -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');
Expand All @@ -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;
}
Expand Down
15 changes: 11 additions & 4 deletions src/hooks/registerHook.ts
Original file line number Diff line number Diff line change
@@ -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);
}
Expand Down
1 change: 1 addition & 0 deletions src/setupCoreModule.ts
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@ import Module = require('module');
export function setupCoreModule(): void {
const coreApi = {
version: version,
supportsStructuredLogProperties: true,
get hostVersion() {
return worker.hostVersion;
},
Expand Down
66 changes: 66 additions & 0 deletions src/utils/structuredLogProperties.ts
Original file line number Diff line number Diff line change
@@ -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<string, string | number | boolean> = 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))
);
}
Loading