@anthropic-field/core 0.1.0

package/dist/src/telemetry/semantic.d.ts

@@ -0,0 +1,82 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * This file contains functions and types for converting Gemini API request/response
+ * formats to the OpenTelemetry semantic conventions for generative AI.
+ *
+ * @see https://github.com/open-telemetry/semantic-conventions/blob/8b4f210f43136e57c1f6f47292eb6d38e3bf30bb/docs/gen-ai/gen-ai-events.md
+ */
+import { FinishReason } from '@google/genai';
+import type { Candidate, Content, ContentUnion, Part } from '@google/genai';
+export declare function toInputMessages(contents: Content[]): InputMessages;
+export declare function toSystemInstruction(systemInstruction?: ContentUnion): SystemInstruction | undefined;
+export declare function toOutputMessages(candidates?: Candidate[]): OutputMessages;
+export declare function toFinishReasons(candidates?: Candidate[]): OTelFinishReason[];
+export declare function toOutputType(requested_mime?: string): string | undefined;
+export declare function toChatMessage(content?: Content): ChatMessage;
+export declare function toOTelPart(part: Part): AnyPart;
+export declare enum OTelRole {
+    SYSTEM = "system",
+    USER = "user",
+    ASSISTANT = "assistant",
+    TOOL = "tool"
+}
+export declare function toOTelRole(role?: string): OTelRole;
+export type InputMessages = ChatMessage[];
+export declare enum OTelOutputType {
+    IMAGE = "image",
+    JSON = "json",
+    SPEECH = "speech",
+    TEXT = "text"
+}
+export declare enum OTelFinishReason {
+    STOP = "stop",
+    LENGTH = "length",
+    CONTENT_FILTER = "content_filter",
+    TOOL_CALL = "tool_call",
+    ERROR = "error"
+}
+export declare function toOTelFinishReason(finishReason?: string): OTelFinishReason;
+export interface OutputMessage extends ChatMessage {
+    finish_reason: FinishReason | string;
+}
+export type OutputMessages = OutputMessage[];
+export type AnyPart = TextPart | ToolCallRequestPart | ToolCallResponsePart | ReasoningPart | GenericPart;
+export type SystemInstruction = AnyPart[];
+export interface ChatMessage {
+    role: string | undefined;
+    parts: AnyPart[];
+}
+export declare class TextPart {
+    readonly type = "text";
+    content: string;
+    constructor(content: string);
+}
+export declare class ToolCallRequestPart {
+    readonly type = "tool_call";
+    name?: string;
+    id?: string;
+    arguments?: string;
+    constructor(name?: string, id?: string, args?: string);
+}
+export declare class ToolCallResponsePart {
+    readonly type = "tool_call_response";
+    response?: string;
+    id?: string;
+    constructor(response?: string, id?: string);
+}
+export declare class ReasoningPart {
+    readonly type = "reasoning";
+    content: string;
+    constructor(content: string);
+}
+export declare class GenericPart {
+    type: string;
+    [key: string]: unknown;
+    constructor(type: string, data: {
+        [key: string]: unknown;
+    });
+}

package/dist/src/telemetry/semantic.js

@@ -0,0 +1,357 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * This file contains functions and types for converting Gemini API request/response
+ * formats to the OpenTelemetry semantic conventions for generative AI.
+ *
+ * @see https://github.com/open-telemetry/semantic-conventions/blob/8b4f210f43136e57c1f6f47292eb6d38e3bf30bb/docs/gen-ai/gen-ai-events.md
+ */
+import { FinishReason } from '@google/genai';
+import { truncateString } from '../utils/textUtils.js';
+// 160KB limit for the total size of string content in a log entry.
+// The total log entry size limit is 256KB. We leave ~96KB (approx 37%) for JSON overhead (escaping, structure) and other fields.
+const GLOBAL_TEXT_LIMIT = 160 * 1024;
+function getStringReferences(parts) {
+    const refs = [];
+    for (const part of parts) {
+        if (part instanceof TextPart) {
+            refs.push({
+                get: () => part.content,
+                set: (val) => (part.content = val),
+                len: () => part.content.length,
+            });
+        }
+        else if (part instanceof ReasoningPart) {
+            refs.push({
+                get: () => part.content,
+                set: (val) => (part.content = val),
+                len: () => part.content.length,
+            });
+        }
+        else if (part instanceof ToolCallRequestPart) {
+            if (part.arguments) {
+                refs.push({
+                    get: () => part.arguments,
+                    set: (val) => (part.arguments = val),
+                    len: () => part.arguments?.length ?? 0,
+                });
+            }
+        }
+        else if (part instanceof ToolCallResponsePart) {
+            if (part.response) {
+                refs.push({
+                    get: () => part.response,
+                    set: (val) => (part.response = val),
+                    len: () => part.response?.length ?? 0,
+                });
+            }
+        }
+        else if (part instanceof GenericPart) {
+            if (part.type === 'executableCode' && typeof part['code'] === 'string') {
+                refs.push({
+                    get: () => part['code'],
+                    set: (val) => (part['code'] = val),
+                    len: () => part['code'].length,
+                });
+            }
+            else if (part.type === 'codeExecutionResult' &&
+                typeof part['output'] === 'string') {
+                refs.push({
+                    get: () => part['output'],
+                    set: (val) => (part['output'] = val),
+                    len: () => part['output'].length,
+                });
+            }
+        }
+    }
+    return refs;
+}
+function limitTotalLength(parts) {
+    const refs = getStringReferences(parts);
+    const totalLength = refs.reduce((sum, ref) => sum + ref.len(), 0);
+    if (totalLength <= GLOBAL_TEXT_LIMIT) {
+        return;
+    }
+    // Calculate the average budget per part for "large" parts.
+    // We identify parts that are larger than the fair share (average) and truncate them.
+    const averageSize = GLOBAL_TEXT_LIMIT / refs.length;
+    // Filter out parts that are already small enough to not need truncation
+    const largeRefs = refs.filter((ref) => ref.len() > averageSize);
+    const smallRefsLength = refs
+        .filter((ref) => ref.len() <= averageSize)
+        .reduce((sum, ref) => sum + ref.len(), 0);
+    // Distribute the remaining budget among large parts
+    const remainingBudget = GLOBAL_TEXT_LIMIT - smallRefsLength;
+    const budgetPerLargePart = Math.max(1, Math.floor(remainingBudget / largeRefs.length));
+    for (const ref of largeRefs) {
+        const original = ref.get();
+        if (original) {
+            ref.set(truncateString(original, budgetPerLargePart));
+        }
+    }
+}
+export function toInputMessages(contents) {
+    const messages = [];
+    for (const content of contents) {
+        messages.push(toChatMessage(content));
+    }
+    const allParts = messages.flatMap((m) => m.parts);
+    limitTotalLength(allParts);
+    return messages;
+}
+function isPart(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        !Array.isArray(value) &&
+        !('parts' in value));
+}
+function toPart(part) {
+    if (typeof part === 'string') {
+        return { text: part };
+    }
+    return part;
+}
+function toContent(content) {
+    if (typeof content === 'string') {
+        // 1. It's a string
+        return {
+            parts: [toPart(content)],
+        };
+    }
+    else if (Array.isArray(content)) {
+        // 2. It's an array of parts (PartUnion[])
+        return {
+            parts: content.map(toPart),
+        };
+    }
+    else if ('parts' in content) {
+        // 3. It's a Content object
+        return content;
+    }
+    else if (isPart(content)) {
+        // 4. It's a single Part object (asserted with type guard)
+        return {
+            parts: [content],
+        };
+    }
+    else {
+        // 5. Handle any other unexpected case
+        return undefined;
+    }
+}
+export function toSystemInstruction(systemInstruction) {
+    const parts = [];
+    if (systemInstruction) {
+        const content = toContent(systemInstruction);
+        if (content && content.parts) {
+            for (const part of content.parts) {
+                parts.push(toOTelPart(part));
+            }
+        }
+    }
+    limitTotalLength(parts);
+    return parts;
+}
+export function toOutputMessages(candidates) {
+    const messages = [];
+    if (candidates) {
+        for (const candidate of candidates) {
+            messages.push({
+                finish_reason: toOTelFinishReason(candidate.finishReason),
+                ...toChatMessage(candidate.content),
+            });
+        }
+    }
+    const allParts = messages.flatMap((m) => m.parts);
+    limitTotalLength(allParts);
+    return messages;
+}
+export function toFinishReasons(candidates) {
+    const reasons = [];
+    if (candidates) {
+        for (const candidate of candidates) {
+            reasons.push(toOTelFinishReason(candidate.finishReason));
+        }
+    }
+    return reasons;
+}
+export function toOutputType(requested_mime) {
+    switch (requested_mime) {
+        // explicitly support the known good values of responseMimeType
+        case 'text/plain':
+            return OTelOutputType.TEXT;
+        case 'application/json':
+            return OTelOutputType.JSON;
+        default:
+            // if none of the well-known values applies, a custom value may be used
+            return requested_mime;
+    }
+}
+export function toChatMessage(content) {
+    const message = {
+        role: undefined,
+        parts: [],
+    };
+    if (content && content.parts) {
+        message.role = toOTelRole(content.role);
+        for (const part of content.parts) {
+            message.parts.push(toOTelPart(part));
+        }
+    }
+    return message;
+}
+export function toOTelPart(part) {
+    if (part.thought) {
+        if (part.text) {
+            return new ReasoningPart(part.text);
+        }
+        else {
+            return new ReasoningPart('');
+        }
+    }
+    else if (part.text) {
+        return new TextPart(part.text);
+    }
+    else if (part.functionCall) {
+        return new ToolCallRequestPart(part.functionCall.name, part.functionCall.id, JSON.stringify(part.functionCall.args));
+    }
+    else if (part.functionResponse) {
+        return new ToolCallResponsePart(JSON.stringify(part.functionResponse.response), part.functionResponse.id);
+    }
+    else if (part.executableCode) {
+        const { executableCode, ...unexpectedData } = part;
+        return new GenericPart('executableCode', {
+            code: executableCode.code,
+            language: executableCode.language,
+            ...unexpectedData,
+        });
+    }
+    else if (part.codeExecutionResult) {
+        const { codeExecutionResult, ...unexpectedData } = part;
+        return new GenericPart('codeExecutionResult', {
+            outcome: codeExecutionResult.outcome,
+            output: codeExecutionResult.output,
+            ...unexpectedData,
+        });
+    }
+    // Assuming the above cases capture all the expected parts
+    // but adding a fallthrough just in case.
+    return new GenericPart('unknown', { ...part });
+}
+export var OTelRole;
+(function (OTelRole) {
+    OTelRole["SYSTEM"] = "system";
+    OTelRole["USER"] = "user";
+    OTelRole["ASSISTANT"] = "assistant";
+    OTelRole["TOOL"] = "tool";
+})(OTelRole || (OTelRole = {}));
+export function toOTelRole(role) {
+    switch (role?.toLowerCase()) {
+        case 'system':
+            return OTelRole.SYSTEM;
+        // Our APIs seem to frequently use 'model'
+        case 'model':
+            return OTelRole.SYSTEM;
+        case 'user':
+            return OTelRole.USER;
+        case 'assistant':
+            return OTelRole.ASSISTANT;
+        case 'tool':
+            return OTelRole.TOOL;
+        default:
+            return OTelRole.SYSTEM;
+    }
+}
+export var OTelOutputType;
+(function (OTelOutputType) {
+    OTelOutputType["IMAGE"] = "image";
+    OTelOutputType["JSON"] = "json";
+    OTelOutputType["SPEECH"] = "speech";
+    OTelOutputType["TEXT"] = "text";
+})(OTelOutputType || (OTelOutputType = {}));
+export var OTelFinishReason;
+(function (OTelFinishReason) {
+    OTelFinishReason["STOP"] = "stop";
+    OTelFinishReason["LENGTH"] = "length";
+    OTelFinishReason["CONTENT_FILTER"] = "content_filter";
+    OTelFinishReason["TOOL_CALL"] = "tool_call";
+    OTelFinishReason["ERROR"] = "error";
+})(OTelFinishReason || (OTelFinishReason = {}));
+export function toOTelFinishReason(finishReason) {
+    switch (finishReason) {
+        // we have significantly more finish reasons than the spec
+        case FinishReason.FINISH_REASON_UNSPECIFIED:
+            return OTelFinishReason.STOP;
+        case FinishReason.STOP:
+            return OTelFinishReason.STOP;
+        case FinishReason.MAX_TOKENS:
+            return OTelFinishReason.LENGTH;
+        case FinishReason.SAFETY:
+            return OTelFinishReason.CONTENT_FILTER;
+        case FinishReason.RECITATION:
+            return OTelFinishReason.CONTENT_FILTER;
+        case FinishReason.LANGUAGE:
+            return OTelFinishReason.CONTENT_FILTER;
+        case FinishReason.OTHER:
+            return OTelFinishReason.STOP;
+        case FinishReason.BLOCKLIST:
+            return OTelFinishReason.CONTENT_FILTER;
+        case FinishReason.PROHIBITED_CONTENT:
+            return OTelFinishReason.CONTENT_FILTER;
+        case FinishReason.SPII:
+            return OTelFinishReason.CONTENT_FILTER;
+        case FinishReason.MALFORMED_FUNCTION_CALL:
+            return OTelFinishReason.ERROR;
+        case FinishReason.IMAGE_SAFETY:
+            return OTelFinishReason.CONTENT_FILTER;
+        case FinishReason.UNEXPECTED_TOOL_CALL:
+            return OTelFinishReason.ERROR;
+        default:
+            return OTelFinishReason.STOP;
+    }
+}
+export class TextPart {
+    type = 'text';
+    content;
+    constructor(content) {
+        this.content = content;
+    }
+}
+export class ToolCallRequestPart {
+    type = 'tool_call';
+    name;
+    id;
+    arguments;
+    constructor(name, id, args) {
+        this.name = name;
+        this.id = id;
+        this.arguments = args;
+    }
+}
+export class ToolCallResponsePart {
+    type = 'tool_call_response';
+    response;
+    id;
+    constructor(response, id) {
+        this.response = response;
+        this.id = id;
+    }
+}
+export class ReasoningPart {
+    type = 'reasoning';
+    content;
+    constructor(content) {
+        this.content = content;
+    }
+}
+export class GenericPart {
+    type;
+    constructor(type, data) {
+        this.type = type;
+        Object.assign(this, data);
+    }
+}
+//# sourceMappingURL=semantic.js.map

package/dist/src/telemetry/semantic.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"semantic.js","sourceRoot":"","sources":["../../../src/telemetry/semantic.ts"],"names":[],"mappings":"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"}

package/dist/src/telemetry/startupProfiler.d.ts

@@ -0,0 +1,51 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { Config } from '../config/config.js';
+/**
+ * Handle returned by start() that allows ending the phase without repeating the phase name.
+ */
+export interface StartupPhaseHandle {
+    end(details?: Record<string, string | number | boolean>): void;
+}
+/**
+ * Buffers startup performance metrics until the telemetry system is fully initialized.
+ */
+export declare class StartupProfiler {
+    private phases;
+    private static instance;
+    private constructor();
+    static getInstance(): StartupProfiler;
+    /**
+     * Returns the mark name for the start of a phase.
+     */
+    private getStartMarkName;
+    /**
+     * Returns the mark name for the end of a phase.
+     */
+    private getEndMarkName;
+    /**
+     * Marks the start of a phase and returns a handle to end it.
+     *
+     * If a phase with the same name is already active (started but not ended),
+     * this method will log a warning and return `undefined`. This allows for
+     * idempotent calls in environments where initialization might happen multiple
+     * times.
+     *
+     * Callers should handle the potential `undefined` return value, typically
+     * by using optional chaining: `handle?.end()`.
+     */
+    start(phaseName: string, details?: Record<string, string | number | boolean>): StartupPhaseHandle | undefined;
+    /**
+     * Marks the end of a phase and calculates duration.
+     * This is now a private method; callers should use the handle returned by start().
+     */
+    private _end;
+    /**
+     * Flushes buffered metrics to the telemetry system.
+     */
+    flush(config: Config): void;
+}
+export declare const startupProfiler: StartupProfiler;

package/dist/src/telemetry/startupProfiler.js

@@ -0,0 +1,170 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { performance } from 'node:perf_hooks';
+import * as os from 'node:os';
+import * as fs from 'node:fs';
+import { recordStartupPerformance } from './metrics.js';
+import { debugLogger } from '../utils/debugLogger.js';
+import { StartupStatsEvent } from './types.js';
+import { logStartupStats } from './loggers.js';
+/**
+ * Buffers startup performance metrics until the telemetry system is fully initialized.
+ */
+export class StartupProfiler {
+    phases = new Map();
+    static instance;
+    constructor() { }
+    static getInstance() {
+        if (!StartupProfiler.instance) {
+            StartupProfiler.instance = new StartupProfiler();
+        }
+        return StartupProfiler.instance;
+    }
+    /**
+     * Returns the mark name for the start of a phase.
+     */
+    getStartMarkName(phaseName) {
+        return `startup:${phaseName}:start`;
+    }
+    /**
+     * Returns the mark name for the end of a phase.
+     */
+    getEndMarkName(phaseName) {
+        return `startup:${phaseName}:end`;
+    }
+    /**
+     * Marks the start of a phase and returns a handle to end it.
+     *
+     * If a phase with the same name is already active (started but not ended),
+     * this method will log a warning and return `undefined`. This allows for
+     * idempotent calls in environments where initialization might happen multiple
+     * times.
+     *
+     * Callers should handle the potential `undefined` return value, typically
+     * by using optional chaining: `handle?.end()`.
+     */
+    start(phaseName, details) {
+        const existingPhase = this.phases.get(phaseName);
+        // Error if starting a phase that's already active.
+        if (existingPhase && !existingPhase.ended) {
+            debugLogger.warn(`[STARTUP] Cannot start phase '${phaseName}': phase is already active. Call end() before starting again.`);
+            return undefined;
+        }
+        const startMarkName = this.getStartMarkName(phaseName);
+        performance.mark(startMarkName, { detail: details });
+        const phase = {
+            name: phaseName,
+            startCpuUsage: process.cpuUsage(),
+            details,
+            ended: false,
+        };
+        this.phases.set(phaseName, phase);
+        // Return a handle that allows ending the phase without repeating the name
+        return {
+            end: (endDetails) => {
+                this._end(phase, endDetails);
+            },
+        };
+    }
+    /**
+     * Marks the end of a phase and calculates duration.
+     * This is now a private method; callers should use the handle returned by start().
+     */
+    _end(phase, details) {
+        // Error if ending a phase that's already ended.
+        if (phase.ended) {
+            debugLogger.warn(`[STARTUP] Cannot end phase '${phase.name}': phase was already ended.`);
+            return;
+        }
+        const startMarkName = this.getStartMarkName(phase.name);
+        const endMarkName = this.getEndMarkName(phase.name);
+        // Check if start mark exists before measuring
+        if (performance.getEntriesByName(startMarkName).length === 0) {
+            debugLogger.warn(`[STARTUP] Cannot measure phase '${phase.name}': start mark '${startMarkName}' not found (likely cleared by reset).`);
+            phase.ended = true;
+            return;
+        }
+        performance.mark(endMarkName, { detail: details });
+        performance.measure(phase.name, startMarkName, endMarkName);
+        phase.cpuUsage = process.cpuUsage(phase.startCpuUsage);
+        phase.ended = true;
+        if (details) {
+            phase.details = { ...phase.details, ...details };
+        }
+    }
+    /**
+     * Flushes buffered metrics to the telemetry system.
+     */
+    flush(config) {
+        debugLogger.debug('[STARTUP] StartupProfiler.flush() called with', this.phases.size, 'phases');
+        const commonDetails = {
+            os_platform: os.platform(),
+            os_arch: os.arch(),
+            os_release: os.release(),
+            is_docker: fs.existsSync('/.dockerenv'),
+        };
+        // Get all performance measures.
+        const measures = performance.getEntriesByType('measure');
+        for (const phase of this.phases.values()) {
+            // Warn about incomplete phases.
+            if (!phase.ended) {
+                debugLogger.warn(`[STARTUP] Phase '${phase.name}' was started but never ended. Skipping metrics.`);
+                continue;
+            }
+            // Find the corresponding measure.
+            const measure = measures.find((m) => m.name === phase.name);
+            if (measure && phase.cpuUsage) {
+                const details = {
+                    ...commonDetails,
+                    cpu_usage_user: phase.cpuUsage.user,
+                    cpu_usage_system: phase.cpuUsage.system,
+                    ...phase.details,
+                };
+                debugLogger.debug('[STARTUP] Recording metric for phase:', phase.name, 'duration:', measure.duration);
+                recordStartupPerformance(config, measure.duration, {
+                    phase: phase.name,
+                    details,
+                });
+            }
+            else {
+                debugLogger.debug('[STARTUP] Skipping phase without measure:', phase.name);
+            }
+        }
+        // Emit StartupStats event
+        const startupPhases = [];
+        for (const phase of this.phases.values()) {
+            if (!phase.ended)
+                continue;
+            const measure = measures.find((m) => m.name === phase.name);
+            if (measure && phase.cpuUsage) {
+                startupPhases.push({
+                    name: phase.name,
+                    duration_ms: measure.duration,
+                    cpu_usage_user_usec: phase.cpuUsage.user,
+                    cpu_usage_system_usec: phase.cpuUsage.system,
+                    start_time_usec: (performance.timeOrigin + measure.startTime) * 1000,
+                    end_time_usec: (performance.timeOrigin + measure.startTime + measure.duration) *
+                        1000,
+                });
+            }
+        }
+        if (startupPhases.length > 0) {
+            logStartupStats(config, new StartupStatsEvent(startupPhases, os.platform(), os.release(), fs.existsSync('/.dockerenv')));
+        }
+        // Clear performance marks and measures for all tracked phases.
+        for (const phaseName of this.phases.keys()) {
+            const startMarkName = this.getStartMarkName(phaseName);
+            const endMarkName = this.getEndMarkName(phaseName);
+            performance.clearMarks(startMarkName);
+            performance.clearMarks(endMarkName);
+            performance.clearMeasures(phaseName);
+        }
+        // Clear all phases.
+        this.phases.clear();
+    }
+}
+export const startupProfiler = StartupProfiler.getInstance();
+//# sourceMappingURL=startupProfiler.js.map