Context7 Platform -- Up-to-date docs for AI agents
import type {
McpHttpHandler,
McpRequestContext,
McpServer,
Implementation,
ServerOptions,
Transport,
} from "@modelcontextprotocol/server";
import type {
AuthenticationEventObservation,
AuthenticationObservation,
AuthenticationObservationOptions,
UpstreamObservationOptions,
UpstreamOperation,
} from "./telemetry-contracts.js";
import { embeddedPrometheusIsEnabled, telemetryIsDisabled } from "./telemetry-config.js";
import type { ToolCallOutcome } from "./tool-names.js";
interface TelemetryStartupOptions {
allowEmbeddedPrometheus: boolean;
serviceVersion: string;
}
interface McpInstrumentation {
createServer(
serverInfo: Implementation,
serverOptions: ServerOptions,
requestContext: McpRequestContext
): McpServer;
instrumentHttpHandler(handler: McpHttpHandler): McpHttpHandler;
instrumentStdioTransport(transport: Transport): Transport;
}
type TelemetryImplementation = typeof import("./telemetry.js");
type McpTelemetryImplementation = typeof import("./mcp-telemetry.js");
const TELEMETRY_DISABLED = telemetryIsDisabled();
let implementation: TelemetryImplementation | undefined;
let implementationPromise: Promise<TelemetryImplementation> | undefined;
let mcpImplementationPromise: Promise<McpTelemetryImplementation> | undefined;
let prometheusStartup: Promise<unknown> | undefined;
function loadImplementation(): Promise<TelemetryImplementation> {
implementationPromise ??= import("./telemetry.js")
.then((loaded) => {
implementation = loaded;
return loaded;
})
.catch((error) => {
implementationPromise = undefined;
throw error;
});
return implementationPromise;
}
function loadMcpImplementation(): Promise<McpTelemetryImplementation> {
mcpImplementationPromise ??= import("./mcp-telemetry.js").catch((error) => {
mcpImplementationPromise = undefined;
throw error;
});
return mcpImplementationPromise;
}
async function startEmbeddedPrometheus(serviceVersion: string): Promise<void> {
prometheusStartup ??= import("./telemetry-provider.js")
.then(({ startPrometheusMetrics }) => startPrometheusMetrics(serviceVersion))
.catch((error) => {
prometheusStartup = undefined;
throw error;
});
await prometheusStartup;
}
export async function initializeTelemetry(
options: TelemetryStartupOptions
): Promise<McpInstrumentation | undefined> {
if (TELEMETRY_DISABLED) return undefined;
const [loadedTelemetry, loadedMcpTelemetry] = await Promise.all([
loadImplementation(),
loadMcpImplementation(),
]);
implementation = loadedTelemetry;
if (options.allowEmbeddedPrometheus && embeddedPrometheusIsEnabled()) {
await startEmbeddedPrometheus(options.serviceVersion);
}
return {
createServer: (serverInfo, serverOptions, requestContext) =>
new loadedMcpTelemetry.InstrumentedMcpServer(serverInfo, serverOptions, requestContext),
instrumentHttpHandler: loadedMcpTelemetry.instrumentMcpHttpHandler,
instrumentStdioTransport: loadedMcpTelemetry.instrumentStdioTransport,
};
}
export async function observeAuthentication<T extends AuthenticationObservation>(
options: AuthenticationObservationOptions,
operation: () => Promise<T>
): Promise<T> {
if (TELEMETRY_DISABLED) return operation();
return (await loadImplementation()).observeAuthentication(options, operation);
}
export function recordAuthenticationEvent(observation: AuthenticationEventObservation): void {
implementation?.recordAuthenticationEvent(observation);
}
export function recordSelfCancellingBatch(userAgent: string | undefined): void {
implementation?.recordSelfCancellingBatch(userAgent);
}
export async function observeUpstreamRequest<T>(
operationName: UpstreamOperation,
request: () => Promise<Response>,
consumeResponse: (response: Response) => Promise<T>,
options: UpstreamObservationOptions = {}
): Promise<T> {
if (TELEMETRY_DISABLED) return consumeResponse(await request());
return (await loadImplementation()).observeUpstreamRequest(
operationName,
request,
consumeResponse,
options
);
}
export function recordToolCallOutcome(outcome: ToolCallOutcome): void {
implementation?.recordToolCallOutcome(outcome);
}
export async function forceFlushTelemetry(): Promise<void> {
await implementation?.forceFlushTelemetry();
}
export type {
AuthenticationEventObservation,
AuthenticationObservation,
AuthenticationObservationOptions,
UpstreamObservationOptions,
UpstreamOperation,
} from "./telemetry-contracts.js";