@cyanheads/mcp-ts-core 0.1.0-beta.12

package/dist/utils/telemetry/metrics.js

@@ -0,0 +1,205 @@
+/**
+ * @fileoverview OpenTelemetry metrics utilities for custom instrumentation.
+ * Provides simplified interfaces for creating and managing counters, histograms,
+ * gauges, and observable metrics. Supports both Node and Worker environments.
+ * @module src/utils/telemetry/metrics
+ */
+import { metrics, } from '@opentelemetry/api';
+import { config } from '../../config/index.js';
+/**
+ * Gets or creates a meter for custom metrics.
+ * Uses application service name and version from config by default.
+ *
+ * @param name - Optional custom meter name (defaults to service name)
+ * @returns Meter instance for creating metrics
+ *
+ * @example
+ * ```typescript
+ * const meter = getMeter('database-metrics');
+ * const queryCounter = meter.createCounter('db.queries');
+ * ```
+ */
+export function getMeter(name) {
+    return metrics.getMeter(name ?? config.openTelemetry.serviceName, config.openTelemetry.serviceVersion);
+}
+/**
+ * Creates a counter metric (monotonically increasing).
+ * Counters are suitable for measuring event counts, request totals, errors, etc.
+ *
+ * @param name - Metric name (should use dot notation, e.g., 'http.requests')
+ * @param description - Human-readable description of what the metric measures
+ * @param unit - Optional unit of measurement (e.g., '1', 'requests', 'bytes')
+ * @returns Counter instance for recording values
+ *
+ * @example
+ * ```typescript
+ * const requestCounter = createCounter(
+ *   'api.requests',
+ *   'Total number of API requests',
+ *   '1'
+ * );
+ *
+ * // Later in code
+ * requestCounter.add(1, {
+ *   'http.method': 'GET',
+ *   'http.route': '/api/users'
+ * });
+ * ```
+ */
+export function createCounter(name, description, unit = '1') {
+    const meter = getMeter();
+    return meter.createCounter(name, { description, unit });
+}
+/**
+ * Creates an up-down counter metric (can increase or decrease).
+ * Suitable for tracking values that fluctuate, like active connections or queue depth.
+ *
+ * @param name - Metric name (should use dot notation, e.g., 'connections.active')
+ * @param description - Human-readable description of what the metric measures
+ * @param unit - Optional unit of measurement (default: '1')
+ * @returns UpDownCounter instance for recording positive and negative deltas
+ *
+ * @example
+ * ```typescript
+ * const activeConnections = createUpDownCounter(
+ *   'connections.active',
+ *   'Number of active connections',
+ *   '{connections}'
+ * );
+ *
+ * activeConnections.add(1);  // New connection
+ * activeConnections.add(-1); // Connection closed
+ * ```
+ */
+export function createUpDownCounter(name, description, unit = '1') {
+    const meter = getMeter();
+    return meter.createUpDownCounter(name, { description, unit });
+}
+/**
+ * Creates a histogram metric for recording distributions.
+ * Histograms are ideal for latency, response times, payload sizes, etc.
+ *
+ * @param name - Metric name (should use dot notation)
+ * @param description - Human-readable description
+ * @param unit - Optional unit (e.g., 'ms', 'bytes', 's')
+ * @returns Histogram instance
+ *
+ * @example
+ * ```typescript
+ * const requestDuration = createHistogram(
+ *   'http.request.duration',
+ *   'HTTP request duration',
+ *   'ms'
+ * );
+ *
+ * const startTime = Date.now();
+ * // ... handle request ...
+ * requestDuration.record(Date.now() - startTime, {
+ *   'http.method': 'POST',
+ *   'http.status_code': 200
+ * });
+ * ```
+ */
+export function createHistogram(name, description, unit) {
+    const meter = getMeter();
+    const options = unit ? { description, unit } : { description };
+    return meter.createHistogram(name, options);
+}
+/**
+ * Creates an observable gauge for async/callback-based measurements.
+ * Gauges are polled periodically by the metrics SDK and report current values.
+ * Use for measuring things like memory usage, queue depth, temperature, etc.
+ *
+ * @param name - Metric name (should use dot notation)
+ * @param description - Human-readable description
+ * @param callback - Async function returning the current metric value
+ * @param unit - Optional unit of measurement
+ * @returns ObservableGauge instance
+ *
+ * @example
+ * ```typescript
+ * // Monitor heap memory usage
+ * createObservableGauge(
+ *   'process.memory.heap_used',
+ *   'Current heap memory usage',
+ *   () => {
+ *     if (typeof process !== 'undefined') {
+ *       return process.memoryUsage().heapUsed;
+ *     }
+ *     return 0;
+ *   },
+ *   'bytes'
+ * );
+ * ```
+ */
+export function createObservableGauge(name, description, callback, unit) {
+    const meter = getMeter();
+    const options = unit ? { description, unit } : { description };
+    const gauge = meter.createObservableGauge(name, options);
+    gauge.addCallback(async (result) => {
+        result.observe(await callback());
+    });
+    return gauge;
+}
+/**
+ * Creates an observable counter for async/callback-based cumulative measurements.
+ * Similar to ObservableGauge but for monotonically increasing values.
+ * The callback is registered via `addCallback` and polled by the metrics SDK on each collection cycle.
+ *
+ * @param name - Metric name (should use dot notation, e.g., 'jobs.processed')
+ * @param description - Human-readable description
+ * @param callback - Async function returning the current cumulative count
+ * @param unit - Optional unit of measurement (default: '1')
+ * @returns ObservableCounter instance
+ *
+ * @example
+ * ```typescript
+ * let totalProcessed = 0;
+ *
+ * createObservableCounter(
+ *   'jobs.processed',
+ *   'Total jobs processed since startup',
+ *   () => totalProcessed,
+ *   '{jobs}'
+ * );
+ * ```
+ */
+export function createObservableCounter(name, description, callback, unit = '1') {
+    const meter = getMeter();
+    const counter = meter.createObservableCounter(name, { description, unit });
+    counter.addCallback(async (result) => {
+        result.observe(await callback());
+    });
+    return counter;
+}
+/**
+ * Creates an observable up-down counter for async/callback-based measurements
+ * that can increase or decrease.
+ * The callback is registered via `addCallback` and polled by the metrics SDK on each collection cycle.
+ *
+ * @param name - Metric name (should use dot notation, e.g., 'queue.size')
+ * @param description - Human-readable description of what the metric measures
+ * @param callback - Async function returning the current value (can be positive or negative)
+ * @param unit - Optional unit of measurement (default: '1')
+ * @returns ObservableUpDownCounter instance
+ *
+ * @example
+ * ```typescript
+ * // Track current queue size
+ * createObservableUpDownCounter(
+ *   'queue.size',
+ *   'Current number of items in queue',
+ *   async () => await getQueueSize(),
+ *   '{items}'
+ * );
+ * ```
+ */
+export function createObservableUpDownCounter(name, description, callback, unit = '1') {
+    const meter = getMeter();
+    const counter = meter.createObservableUpDownCounter(name, { description, unit });
+    counter.addCallback(async (result) => {
+        result.observe(await callback());
+    });
+    return counter;
+}
+//# sourceMappingURL=metrics.js.map

package/dist/utils/telemetry/metrics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.js","sourceRoot":"","sources":["../../../src/utils/telemetry/metrics.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAIL,OAAO,GAER,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAE3C;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,QAAQ,CAAC,IAAa;IACpC,OAAO,OAAO,CAAC,QAAQ,CACrB,IAAI,IAAI,MAAM,CAAC,aAAa,CAAC,WAAW,EACxC,MAAM,CAAC,aAAa,CAAC,cAAc,CACpC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,aAAa,CAAC,IAAY,EAAE,WAAmB,EAAE,IAAI,GAAG,GAAG;IACzE,MAAM,KAAK,GAAG,QAAQ,EAAE,CAAC;IACzB,OAAO,KAAK,CAAC,aAAa,CAAC,IAAI,EAAE,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC,CAAC;AAC1D,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAY,EAAE,WAAmB,EAAE,IAAI,GAAG,GAAG;IAC/E,MAAM,KAAK,GAAG,QAAQ,EAAE,CAAC;IACzB,OAAO,KAAK,CAAC,mBAAmB,CAAC,IAAI,EAAE,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC,CAAC;AAChE,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,eAAe,CAAC,IAAY,EAAE,WAAmB,EAAE,IAAa;IAC9E,MAAM,KAAK,GAAG,QAAQ,EAAE,CAAC;IACzB,MAAM,OAAO,GAAG,IAAI,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC;IAC/D,OAAO,KAAK,CAAC,eAAe,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;AAC9C,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,UAAU,qBAAqB,CACnC,IAAY,EACZ,WAAmB,EACnB,QAAwC,EACxC,IAAa;IAEb,MAAM,KAAK,GAAG,QAAQ,EAAE,CAAC;IACzB,MAAM,OAAO,GAAG,IAAI,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC;IAC/D,MAAM,KAAK,GAAG,KAAK,CAAC,qBAAqB,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IACzD,KAAK,CAAC,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE;QACjC,MAAM,CAAC,OAAO,CAAC,MAAM,QAAQ,EAAE,CAAC,CAAC;IACnC,CAAC,CAAC,CAAC;IACH,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,uBAAuB,CACrC,IAAY,EACZ,WAAmB,EACnB,QAAwC,EACxC,IAAI,GAAG,GAAG;IAEV,MAAM,KAAK,GAAG,QAAQ,EAAE,CAAC;IACzB,MAAM,OAAO,GAAG,KAAK,CAAC,uBAAuB,CAAC,IAAI,EAAE,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC,CAAC;IAC3E,OAAO,CAAC,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE;QACnC,MAAM,CAAC,OAAO,CAAC,MAAM,QAAQ,EAAE,CAAC,CAAC;IACnC,CAAC,CAAC,CAAC;IACH,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,6BAA6B,CAC3C,IAAY,EACZ,WAAmB,EACnB,QAAwC,EACxC,IAAI,GAAG,GAAG;IAEV,MAAM,KAAK,GAAG,QAAQ,EAAE,CAAC;IACzB,MAAM,OAAO,GAAG,KAAK,CAAC,6BAA6B,CAAC,IAAI,EAAE,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC,CAAC;IACjF,OAAO,CAAC,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE;QACnC,MAAM,CAAC,OAAO,CAAC,MAAM,QAAQ,EAAE,CAAC,CAAC;IACnC,CAAC,CAAC,CAAC;IACH,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/utils/telemetry/semconv.d.ts

@@ -0,0 +1,147 @@
+/**
+ * @fileoverview Defines local OpenTelemetry semantic convention constants to ensure
+ * stability and avoid dependency conflicts with different versions of
+ * `@opentelemetry/semantic-conventions`.
+ *
+ * This module provides both standard OTEL conventions (aligned with 1.37+) and
+ * custom MCP-specific attributes for tool execution and resource monitoring.
+ *
+ * @module src/utils/telemetry/semconv
+ */
+/**
+ * Logical name of the service (e.g., `my-mcp-server`).
+ * @see https://opentelemetry.io/docs/specs/semconv/resource/#service
+ */
+export declare const ATTR_SERVICE_NAME = "service.name";
+/** Semantic version of the service (e.g., `1.2.3`). */
+export declare const ATTR_SERVICE_VERSION = "service.version";
+/** Unique ID of the running service instance (e.g., a UUID or pod name). */
+export declare const ATTR_SERVICE_INSTANCE_ID = "service.instance.id";
+/**
+ * Name of the deployment environment (e.g., `production`, `staging`, `development`).
+ * @see https://opentelemetry.io/docs/specs/semconv/resource/deployment-environment/
+ */
+export declare const ATTR_DEPLOYMENT_ENVIRONMENT_NAME = "deployment.environment.name";
+/**
+ * Name of the cloud provider (e.g., `aws`, `gcp`, `azure`, `cloudflare`).
+ * @see https://opentelemetry.io/docs/specs/semconv/resource/cloud/
+ */
+export declare const ATTR_CLOUD_PROVIDER = "cloud.provider";
+/** Cloud platform within the provider (e.g., `aws_lambda`, `gcp_cloud_run`, `cloudflare_workers`). */
+export declare const ATTR_CLOUD_PLATFORM = "cloud.platform";
+/** Geographic region of the cloud resource (e.g., `us-east-1`). */
+export declare const ATTR_CLOUD_REGION = "cloud.region";
+/** Availability zone within the cloud region. */
+export declare const ATTR_CLOUD_AVAILABILITY_ZONE = "cloud.availability_zone";
+/** Cloud account or project ID that owns the resource. */
+export declare const ATTR_CLOUD_ACCOUNT_ID = "cloud.account.id";
+/**
+ * HTTP request method (e.g., `GET`, `POST`).
+ * @see https://opentelemetry.io/docs/specs/semconv/http/
+ */
+export declare const ATTR_HTTP_REQUEST_METHOD = "http.request.method";
+/** HTTP response status code (e.g., `200`, `404`). */
+export declare const ATTR_HTTP_RESPONSE_STATUS_CODE = "http.response.status_code";
+/** HTTP route template matched by the server (e.g., `/users/:id`). */
+export declare const ATTR_HTTP_ROUTE = "http.route";
+/** Size of the HTTP request body in bytes. */
+export declare const ATTR_HTTP_REQUEST_BODY_SIZE = "http.request.body.size";
+/** Size of the HTTP response body in bytes. */
+export declare const ATTR_HTTP_RESPONSE_BODY_SIZE = "http.response.body.size";
+/** Full URL of the request including scheme, host, path, and query. */
+export declare const ATTR_URL_FULL = "url.full";
+/** URL path component (e.g., `/api/users`). */
+export declare const ATTR_URL_PATH = "url.path";
+/** URL query string (e.g., `?limit=10&offset=0`). */
+export declare const ATTR_URL_QUERY = "url.query";
+/** URL scheme (e.g., `http`, `https`). */
+export declare const ATTR_URL_SCHEME = "url.scheme";
+/**
+ * Describes the class or type of error (e.g., `TimeoutError`, `500`).
+ * @see https://opentelemetry.io/docs/specs/semconv/exceptions/
+ */
+export declare const ATTR_ERROR_TYPE = "error.type";
+/** Fully qualified exception class name (e.g., `java.io.IOException`). */
+export declare const ATTR_EXCEPTION_TYPE = "exception.type";
+/** Exception message string. */
+export declare const ATTR_EXCEPTION_MESSAGE = "exception.message";
+/** Full exception stack trace as a string. */
+export declare const ATTR_EXCEPTION_STACKTRACE = "exception.stacktrace";
+/**
+ * Name of the function or method being instrumented.
+ * @see https://opentelemetry.io/docs/specs/semconv/general/attributes/
+ */
+export declare const ATTR_CODE_FUNCTION = "code.function";
+/** Fully qualified namespace or module containing the function (e.g., `com.example.MyClass`). */
+export declare const ATTR_CODE_NAMESPACE = "code.namespace";
+/** Source file path containing the instrumented code. */
+export declare const ATTR_CODE_FILEPATH = "code.filepath";
+/** Line number in the source file where the instrumented code starts. */
+export declare const ATTR_CODE_LINENO = "code.lineno";
+/**
+ * IP address or hostname of the remote peer.
+ * @see https://opentelemetry.io/docs/specs/semconv/general/attributes/
+ */
+export declare const ATTR_NETWORK_PEER_ADDRESS = "network.peer.address";
+/** Port number of the remote peer. */
+export declare const ATTR_NETWORK_PEER_PORT = "network.peer.port";
+/** Application-layer protocol name (e.g., `http`, `grpc`, `amqp`). */
+export declare const ATTR_NETWORK_PROTOCOL_NAME = "network.protocol.name";
+/** Version of the application-layer protocol (e.g., `1.1`, `2`). */
+export declare const ATTR_NETWORK_PROTOCOL_VERSION = "network.protocol.version";
+/**
+ * Unparsed `User-Agent` header value from the HTTP request.
+ */
+export declare const ATTR_USER_AGENT_ORIGINAL = "user_agent.original";
+/**
+ * Registered name of the MCP tool being invoked (e.g., `echo_message`).
+ * Custom attribute specific to MCP tool invocations.
+ */
+export declare const ATTR_MCP_TOOL_NAME = "mcp.tool.name";
+/** Serialized byte size of the tool's input arguments. */
+export declare const ATTR_MCP_TOOL_INPUT_BYTES = "mcp.tool.input_bytes";
+/** Serialized byte size of the tool's output result. */
+export declare const ATTR_MCP_TOOL_OUTPUT_BYTES = "mcp.tool.output_bytes";
+/** Wall-clock execution duration of the tool handler in milliseconds. */
+export declare const ATTR_MCP_TOOL_DURATION_MS = "mcp.tool.duration_ms";
+/** Whether the tool handler completed successfully (`true`) or with an error (`false`). */
+export declare const ATTR_MCP_TOOL_SUCCESS = "mcp.tool.success";
+/** JSON-RPC error code from the thrown `McpError`, present when `mcp.tool.success` is `false`. */
+export declare const ATTR_MCP_TOOL_ERROR_CODE = "mcp.tool.error_code";
+/**
+ * Process Resident Set Size (RSS) in bytes immediately before tool handler execution.
+ */
+export declare const ATTR_MCP_TOOL_MEMORY_RSS_BEFORE = "mcp.tool.memory_rss_bytes.before";
+/** Process RSS in bytes immediately after tool handler execution. */
+export declare const ATTR_MCP_TOOL_MEMORY_RSS_AFTER = "mcp.tool.memory_rss_bytes.after";
+/** Change in process RSS (after minus before) during tool handler execution. */
+export declare const ATTR_MCP_TOOL_MEMORY_RSS_DELTA = "mcp.tool.memory_rss_bytes.delta";
+/**
+ * V8 heap memory used in bytes immediately before tool handler execution.
+ */
+export declare const ATTR_MCP_TOOL_MEMORY_HEAP_USED_BEFORE = "mcp.tool.memory_heap_used_bytes.before";
+/** V8 heap memory used in bytes immediately after tool handler execution. */
+export declare const ATTR_MCP_TOOL_MEMORY_HEAP_USED_AFTER = "mcp.tool.memory_heap_used_bytes.after";
+/** Change in V8 heap used (after minus before) during tool handler execution. */
+export declare const ATTR_MCP_TOOL_MEMORY_HEAP_USED_DELTA = "mcp.tool.memory_heap_used_bytes.delta";
+/**
+ * Full URI identifying the MCP resource being accessed (e.g., `myscheme://items/123`).
+ */
+export declare const ATTR_MCP_RESOURCE_URI = "mcp.resource.uri";
+/** MIME type of the resource content (e.g., `application/json`, `text/plain`). */
+export declare const ATTR_MCP_RESOURCE_MIME_TYPE = "mcp.resource.mime_type";
+/** Byte size of the resource content returned by the handler. */
+export declare const ATTR_MCP_RESOURCE_SIZE_BYTES = "mcp.resource.size_bytes";
+/**
+ * Unique identifier for the MCP request, auto-generated per invocation.
+ */
+export declare const ATTR_MCP_REQUEST_ID = "mcp.request.id";
+/** Name of the MCP operation being performed (e.g., `tools/call`, `resources/read`). */
+export declare const ATTR_MCP_OPERATION_NAME = "mcp.operation.name";
+/** Tenant identifier from the JWT `tid` claim, used for multi-tenant storage scoping. */
+export declare const ATTR_MCP_TENANT_ID = "mcp.tenant.id";
+/** OAuth client identifier from the JWT `cid` or `client_id` claim. */
+export declare const ATTR_MCP_CLIENT_ID = "mcp.client.id";
+/** MCP transport session identifier, scoped to a single client connection. */
+export declare const ATTR_MCP_SESSION_ID = "mcp.session.id";
+//# sourceMappingURL=semconv.d.ts.map

package/dist/utils/telemetry/semconv.d.ts.map

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

package/dist/utils/telemetry/semconv.js

@@ -0,0 +1,159 @@
+/**
+ * @fileoverview Defines local OpenTelemetry semantic convention constants to ensure
+ * stability and avoid dependency conflicts with different versions of
+ * `@opentelemetry/semantic-conventions`.
+ *
+ * This module provides both standard OTEL conventions (aligned with 1.37+) and
+ * custom MCP-specific attributes for tool execution and resource monitoring.
+ *
+ * @module src/utils/telemetry/semconv
+ */
+// ============================================================================
+// Standard OpenTelemetry Semantic Conventions (Stable)
+// ============================================================================
+/**
+ * Logical name of the service (e.g., `my-mcp-server`).
+ * @see https://opentelemetry.io/docs/specs/semconv/resource/#service
+ */
+export const ATTR_SERVICE_NAME = 'service.name';
+/** Semantic version of the service (e.g., `1.2.3`). */
+export const ATTR_SERVICE_VERSION = 'service.version';
+/** Unique ID of the running service instance (e.g., a UUID or pod name). */
+export const ATTR_SERVICE_INSTANCE_ID = 'service.instance.id';
+/**
+ * Name of the deployment environment (e.g., `production`, `staging`, `development`).
+ * @see https://opentelemetry.io/docs/specs/semconv/resource/deployment-environment/
+ */
+export const ATTR_DEPLOYMENT_ENVIRONMENT_NAME = 'deployment.environment.name';
+/**
+ * Name of the cloud provider (e.g., `aws`, `gcp`, `azure`, `cloudflare`).
+ * @see https://opentelemetry.io/docs/specs/semconv/resource/cloud/
+ */
+export const ATTR_CLOUD_PROVIDER = 'cloud.provider';
+/** Cloud platform within the provider (e.g., `aws_lambda`, `gcp_cloud_run`, `cloudflare_workers`). */
+export const ATTR_CLOUD_PLATFORM = 'cloud.platform';
+/** Geographic region of the cloud resource (e.g., `us-east-1`). */
+export const ATTR_CLOUD_REGION = 'cloud.region';
+/** Availability zone within the cloud region. */
+export const ATTR_CLOUD_AVAILABILITY_ZONE = 'cloud.availability_zone';
+/** Cloud account or project ID that owns the resource. */
+export const ATTR_CLOUD_ACCOUNT_ID = 'cloud.account.id';
+/**
+ * HTTP request method (e.g., `GET`, `POST`).
+ * @see https://opentelemetry.io/docs/specs/semconv/http/
+ */
+export const ATTR_HTTP_REQUEST_METHOD = 'http.request.method';
+/** HTTP response status code (e.g., `200`, `404`). */
+export const ATTR_HTTP_RESPONSE_STATUS_CODE = 'http.response.status_code';
+/** HTTP route template matched by the server (e.g., `/users/:id`). */
+export const ATTR_HTTP_ROUTE = 'http.route';
+/** Size of the HTTP request body in bytes. */
+export const ATTR_HTTP_REQUEST_BODY_SIZE = 'http.request.body.size';
+/** Size of the HTTP response body in bytes. */
+export const ATTR_HTTP_RESPONSE_BODY_SIZE = 'http.response.body.size';
+/** Full URL of the request including scheme, host, path, and query. */
+export const ATTR_URL_FULL = 'url.full';
+/** URL path component (e.g., `/api/users`). */
+export const ATTR_URL_PATH = 'url.path';
+/** URL query string (e.g., `?limit=10&offset=0`). */
+export const ATTR_URL_QUERY = 'url.query';
+/** URL scheme (e.g., `http`, `https`). */
+export const ATTR_URL_SCHEME = 'url.scheme';
+/**
+ * Describes the class or type of error (e.g., `TimeoutError`, `500`).
+ * @see https://opentelemetry.io/docs/specs/semconv/exceptions/
+ */
+export const ATTR_ERROR_TYPE = 'error.type';
+/** Fully qualified exception class name (e.g., `java.io.IOException`). */
+export const ATTR_EXCEPTION_TYPE = 'exception.type';
+/** Exception message string. */
+export const ATTR_EXCEPTION_MESSAGE = 'exception.message';
+/** Full exception stack trace as a string. */
+export const ATTR_EXCEPTION_STACKTRACE = 'exception.stacktrace';
+/**
+ * Name of the function or method being instrumented.
+ * @see https://opentelemetry.io/docs/specs/semconv/general/attributes/
+ */
+export const ATTR_CODE_FUNCTION = 'code.function';
+/** Fully qualified namespace or module containing the function (e.g., `com.example.MyClass`). */
+export const ATTR_CODE_NAMESPACE = 'code.namespace';
+/** Source file path containing the instrumented code. */
+export const ATTR_CODE_FILEPATH = 'code.filepath';
+/** Line number in the source file where the instrumented code starts. */
+export const ATTR_CODE_LINENO = 'code.lineno';
+/**
+ * IP address or hostname of the remote peer.
+ * @see https://opentelemetry.io/docs/specs/semconv/general/attributes/
+ */
+export const ATTR_NETWORK_PEER_ADDRESS = 'network.peer.address';
+/** Port number of the remote peer. */
+export const ATTR_NETWORK_PEER_PORT = 'network.peer.port';
+/** Application-layer protocol name (e.g., `http`, `grpc`, `amqp`). */
+export const ATTR_NETWORK_PROTOCOL_NAME = 'network.protocol.name';
+/** Version of the application-layer protocol (e.g., `1.1`, `2`). */
+export const ATTR_NETWORK_PROTOCOL_VERSION = 'network.protocol.version';
+/**
+ * Unparsed `User-Agent` header value from the HTTP request.
+ */
+export const ATTR_USER_AGENT_ORIGINAL = 'user_agent.original';
+// ============================================================================
+// Custom MCP Tool Execution Attributes
+// ============================================================================
+/**
+ * Registered name of the MCP tool being invoked (e.g., `echo_message`).
+ * Custom attribute specific to MCP tool invocations.
+ */
+export const ATTR_MCP_TOOL_NAME = 'mcp.tool.name';
+/** Serialized byte size of the tool's input arguments. */
+export const ATTR_MCP_TOOL_INPUT_BYTES = 'mcp.tool.input_bytes';
+/** Serialized byte size of the tool's output result. */
+export const ATTR_MCP_TOOL_OUTPUT_BYTES = 'mcp.tool.output_bytes';
+/** Wall-clock execution duration of the tool handler in milliseconds. */
+export const ATTR_MCP_TOOL_DURATION_MS = 'mcp.tool.duration_ms';
+/** Whether the tool handler completed successfully (`true`) or with an error (`false`). */
+export const ATTR_MCP_TOOL_SUCCESS = 'mcp.tool.success';
+/** JSON-RPC error code from the thrown `McpError`, present when `mcp.tool.success` is `false`. */
+export const ATTR_MCP_TOOL_ERROR_CODE = 'mcp.tool.error_code';
+/**
+ * Process Resident Set Size (RSS) in bytes immediately before tool handler execution.
+ */
+export const ATTR_MCP_TOOL_MEMORY_RSS_BEFORE = 'mcp.tool.memory_rss_bytes.before';
+/** Process RSS in bytes immediately after tool handler execution. */
+export const ATTR_MCP_TOOL_MEMORY_RSS_AFTER = 'mcp.tool.memory_rss_bytes.after';
+/** Change in process RSS (after minus before) during tool handler execution. */
+export const ATTR_MCP_TOOL_MEMORY_RSS_DELTA = 'mcp.tool.memory_rss_bytes.delta';
+/**
+ * V8 heap memory used in bytes immediately before tool handler execution.
+ */
+export const ATTR_MCP_TOOL_MEMORY_HEAP_USED_BEFORE = 'mcp.tool.memory_heap_used_bytes.before';
+/** V8 heap memory used in bytes immediately after tool handler execution. */
+export const ATTR_MCP_TOOL_MEMORY_HEAP_USED_AFTER = 'mcp.tool.memory_heap_used_bytes.after';
+/** Change in V8 heap used (after minus before) during tool handler execution. */
+export const ATTR_MCP_TOOL_MEMORY_HEAP_USED_DELTA = 'mcp.tool.memory_heap_used_bytes.delta';
+// ============================================================================
+// Custom MCP Resource Attributes
+// ============================================================================
+/**
+ * Full URI identifying the MCP resource being accessed (e.g., `myscheme://items/123`).
+ */
+export const ATTR_MCP_RESOURCE_URI = 'mcp.resource.uri';
+/** MIME type of the resource content (e.g., `application/json`, `text/plain`). */
+export const ATTR_MCP_RESOURCE_MIME_TYPE = 'mcp.resource.mime_type';
+/** Byte size of the resource content returned by the handler. */
+export const ATTR_MCP_RESOURCE_SIZE_BYTES = 'mcp.resource.size_bytes';
+// ============================================================================
+// Custom MCP Request Context Attributes
+// ============================================================================
+/**
+ * Unique identifier for the MCP request, auto-generated per invocation.
+ */
+export const ATTR_MCP_REQUEST_ID = 'mcp.request.id';
+/** Name of the MCP operation being performed (e.g., `tools/call`, `resources/read`). */
+export const ATTR_MCP_OPERATION_NAME = 'mcp.operation.name';
+/** Tenant identifier from the JWT `tid` claim, used for multi-tenant storage scoping. */
+export const ATTR_MCP_TENANT_ID = 'mcp.tenant.id';
+/** OAuth client identifier from the JWT `cid` or `client_id` claim. */
+export const ATTR_MCP_CLIENT_ID = 'mcp.client.id';
+/** MCP transport session identifier, scoped to a single client connection. */
+export const ATTR_MCP_SESSION_ID = 'mcp.session.id';
+//# sourceMappingURL=semconv.js.map

package/dist/utils/telemetry/semconv.js.map

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