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
8 changes: 8 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -65,3 +65,11 @@ app.http('httpTrigger1', {
}
});
```

## Opt-in structured log properties

Enable extraction during application startup with `app.setup({ structuredLogProperties: 'lastPlainObject' })`. Existing calls such as `context.error('Job submission failed', { model: 'olive', errorCode: 'COMPONENT_NOT_FOUND' })` keep their original formatted message and additionally expose the final plain object's own enumerable string, boolean and finite-number properties as `LogHookContext.attributes`. The option is disabled by default. Earlier arguments, arrays, Error instances and nested objects are not sources of structured properties.

A log exporter registers with `app.hook.log(handler, { structuredLogProperties: true })` once it can export the attributes. This requires a worker advertising `supportsStructuredLogProperties` and a compatible exporter; enabling the library option alone does not make fields queryable in Application Insights. Unsupported workers keep the original text and issue a system warning once per invocation. Invalid or reserved properties are omitted with bounded diagnostics that do not include their values; getters are not invoked by extraction. The original text is unchanged, so omitting a property from attributes does not redact it from the message.

Reserved keys include `CategoryName`, `__proto__`, `prototype`, `constructor`, and names beginning with `exception.`, `_MS`, `microsoft` or `ai.` (case-insensitive). These prevent application properties from changing exporter routing or correlation. Diagnostics and buffering remain subject to the configured logging pipeline; this option does not guarantee delivery after process or network failure.
24 changes: 23 additions & 1 deletion src/InvocationModel.ts
Original file line number Diff line number Diff line change
Expand Up @@ -26,12 +26,15 @@ import { waitForProxyRequest } from './http/httpProxy';
import { createStreamRequest } from './http/HttpRequest';
import { InvocationContext } from './InvocationContext';
import { PromptInvocationContext } from './mcp/PromptInvocationContext';
import { enableHttpStream } from './setup';
import { enableHttpStream, structuredLogProperties } from './setup';
import { extractLogAttributes } from './utils/extractLogAttributes';
import { isHttpTrigger, isMcpPromptTrigger, isMcpToolTrigger, isTimerTrigger, isTrigger } from './utils/isTrigger';
import { isDefined, nonNullProp, nonNullValue } from './utils/nonNull';
import { tryGetCoreApiLazy } from './utils/tryGetCoreApiLazy';

export class InvocationModel implements coreTypes.InvocationModel {
#isDone = false;
#structuredLogWarnings = new Set<string>();
#coreCtx: CoreInvocationContext;
#functionName: string;
#bindings: Record<string, RpcBindingInfo>;
Expand Down Expand Up @@ -195,6 +198,25 @@ export class InvocationModel implements coreTypes.InvocationModel {
badAsyncMsg += `Function name: ${this.#functionName}. Invocation Id: ${this.#coreCtx.invocationId}.`;
this.#systemLog('warning', badAsyncMsg);
}
if (structuredLogProperties === 'lastPlainObject') {
const extracted = extractLogAttributes(args[args.length - 1]);
if (extracted.reason) {
this.#structuredLogWarning(extracted.reason, extracted.rejectedCount);
}
if (extracted.attributes) {
if (tryGetCoreApiLazy()?.supportsStructuredLogProperties) {
this.#coreCtx.log(level, 'user', format(...args), { attributes: extracted.attributes });
return;
}
this.#structuredLogWarning('structured_log_worker_unavailable', 0);
}
}
this.#log(level, 'user', ...args);
}
#structuredLogWarning(reason: string, rejectedCount: number): void {
if (!this.#structuredLogWarnings.has(reason)) {
this.#structuredLogWarnings.add(reason);
this.#systemLog('warning', `${reason}: rejectedProperties=${rejectedCount}`);
}
}
}
8 changes: 8 additions & 0 deletions src/hooks/LogHookContext.ts
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,14 @@ export class LogHookContext extends HookContext implements types.LogHookContext
throw new ReadOnlyError('category');
}

get attributes(): Readonly<Record<string, string | number | boolean>> | undefined {
return this.#init.attributes;
}

set attributes(_value: Readonly<Record<string, string | number | boolean>> | undefined) {
throw new ReadOnlyError('attributes');
}

get invocationContext(): types.InvocationContext | undefined {
return this.#init.invocationContext;
}
Expand Down
23 changes: 17 additions & 6 deletions src/hooks/registerHook.ts
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@ import {
AppStartHandler,
AppTerminateHandler,
LogHookHandler,
LogHookOptions,
PostInvocationHandler,
PreInvocationHandler,
} from '@azure/functions';
Expand All @@ -18,7 +19,11 @@ import { LogHookContext } from './LogHookContext';
import { PostInvocationContext } from './PostInvocationContext';
import { PreInvocationContext } from './PreInvocationContext';

function registerHook(hookName: string, callback: coreTypes.HookCallback): coreTypes.Disposable {
function registerHook(
hookName: string,
callback: coreTypes.HookCallback,
options?: LogHookOptions
): coreTypes.Disposable {
const coreApi = tryGetCoreApiLazy();
if (!coreApi) {
console.warn(
Expand All @@ -30,7 +35,9 @@ function registerHook(hookName: string, callback: coreTypes.HookCallback): coreT
);
});
} else {
return coreApi.registerHook(hookName, callback);
return hookName === 'log' && options
? coreApi.registerHook(hookName, callback, options)
: coreApi.registerHook(hookName, callback);
}
}

Expand Down Expand Up @@ -58,11 +65,15 @@ export function postInvocation(handler: PostInvocationHandler): Disposable {
});
}

export function log(handler: LogHookHandler): Disposable {
export function log(handler: LogHookHandler, options?: LogHookOptions): Disposable {
try {
return registerHook('log', (coreContext) => {
return handler(new LogHookContext(coreContext));
});
return registerHook(
'log',
(coreContext) => {
return handler(new LogHookContext(coreContext));
},
options
);
} catch (err) {
const error = ensureErrorType(err);
if (error.name === 'RangeError' && error.isAzureFunctionsSystemError) {
Expand Down
8 changes: 8 additions & 0 deletions src/setup.ts
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@ export function lockSetup(): void {
setupLocked = true;
}

export let structuredLogProperties: SetupOptions['structuredLogProperties'];
export let enableHttpStream = false;
export const capabilities: Record<string, string> = {};

Expand All @@ -20,6 +21,13 @@ export function setup(opts: SetupOptions): void {
throw new AzFuncSystemError("Setup options can't be changed after app startup has finished.");
}

if (isDefined(opts.structuredLogProperties)) {
if (opts.structuredLogProperties !== 'lastPlainObject') {
throw new AzFuncSystemError('Unsupported structuredLogProperties option.');
}
structuredLogProperties = opts.structuredLogProperties;
}

if (opts.enableHttpStream) {
// NOTE: coreApi.log was coincidentally added the same time as http streaming,
// so we can use that to validate the host version instead of messing with semver parsing
Expand Down
63 changes: 63 additions & 0 deletions src/utils/extractLogAttributes.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,63 @@
// Copyright (c) .NET Foundation. All rights reserved.
// Licensed under the MIT License.

export function extractLogAttributes(argument: unknown): ExtractedLogAttributes {
if (typeof argument !== 'object' || argument === null) {
return { rejectedCount: 0 };
}
try {
const prototype: unknown = Object.getPrototypeOf(argument);
if (prototype !== Object.prototype && prototype !== null) {
return { rejectedCount: 0 };
}
const attributes: Record<string, string | number | boolean> = Object.create(null) as Record<
string,
string | number | boolean
>;
let rejectedCount = 0;
for (const propertyName of Object.getOwnPropertyNames(argument)) {
const descriptor = Object.getOwnPropertyDescriptor(argument, propertyName);
if (!descriptor?.enumerable) {
continue;
}
const propertyValue: unknown = descriptor.value;
if (!('value' in descriptor) || isReservedLogProperty(propertyName) || !isLogPropertyValue(propertyValue)) {
rejectedCount++;
} else {
attributes[propertyName] = propertyValue;
}
}
return {
attributes: Object.freeze(attributes),
rejectedCount,
reason: rejectedCount ? 'structured_log_invalid_properties' : undefined,
};
} catch {
return { rejectedCount: 0, reason: 'structured_log_inspection_failed' };
}
}

function isReservedLogProperty(propertyName: string): boolean {
const name = propertyName.toLowerCase();
return (
name === 'categoryname' ||
name === '__proto__' ||
name === 'prototype' ||
name === 'constructor' ||
['exception.', '_ms', 'microsoft', 'ai.'].some((prefix) => name.startsWith(prefix))
);
}

function isLogPropertyValue(propertyValue: unknown): propertyValue is string | number | boolean {
return (
typeof propertyValue === 'string' ||
typeof propertyValue === 'boolean' ||
(typeof propertyValue === 'number' && Number.isFinite(propertyValue))
);
}

interface ExtractedLogAttributes {
attributes?: Readonly<Record<string, string | number | boolean>>;
rejectedCount: number;
reason?: 'structured_log_invalid_properties' | 'structured_log_inspection_failed';
}
Loading