@superblocksteam/telemetry 2.0.93 → 2.0.94-next.1

package/dist-esm/common/contracts/tier2-traces.js

@@ -1,177 +1,520 @@
 /**
- * Tier 2 Traces Contract
+ * Tier 2 Traces Contract (v0.2.0)
  *
- * This file defines the Tier 2 telemetry contract:
- * - Forbidden attributes (removed by Collector)
- * - Hashed attributes (pseudonymized by Collector)
- * - Dropped attributes (removed by Collector)
- * - Forbidden value patterns (for lint-time detection)
+ * Single source of truth for Tier 2 sanitized trace telemetry.
+ * Mirrors: engineering/projects/o11y-refactor/contracts/tier2-traces.v0.2.0.json
  *
- * ENFORCEMENT: The OTEL Collector handles runtime enforcement.
- * These definitions are used for:
- * - ESLint rules (static analysis at CI time)
- * - Development warnings (guardrails.ts)
+ * Used by:
+ * - trace-sanitizer (SDK: which spans/attributes to export)
+ * - lint/forbidden-attributes (ESLint)
+ * - guardrails (dev-time warnings)
  * - Collector config generation
  *
- * See: obs/otel-collector/config-tiered.yaml
- * Source of truth: engineering/projects/o11y-refactor/contracts/tier2-traces.v0.3.0.json
+ * "request handler *" is a local extension for Express instrumentation (not in JSON).
  */
+import { DeploymentTypeEnum } from "@superblocksteam/shared";
+export function getAttributeName(attr) {
+    return typeof attr === "string" ? attr : attr.name;
+}
 /**
- * Attributes that are FORBIDDEN in Tier 2 telemetry.
- * These contain sensitive data that should never leave the customer's environment.
- * The Collector strips these entirely (not hashed, not present in Tier 2).
+ * Span patterns from tier2-traces.v0.2.0.json.
+ * Suffix wildcard only: "HTTP POST *" matches "HTTP POST /api/..." or "POST /api/...".
  */
-export const TIER2_FORBIDDEN_ATTRIBUTES = new Set([
-    // LLM/AI content
-    'llmobs.input',
-    'llmobs.output',
-    'prompt',
-    'code',
-    'tool_input',
-    'tool_output',
-    // File content
-    'file_path',
-    'file_content',
-    // Database content
-    'db.statement',
-    'db.query_text',
-    'db.query.text',
-    // HTTP bodies and URLs
-    'http.request.body',
-    'http.response.body',
-    'url.full',
-    'url.query',
-    'http.url',
-    'http.target',
-    // Resource identifiers (names are customer-specific)
-    'api-id',
-    'api_id',
-    'api-name',
-    'api_name',
-    'resource-id',
-    'resource_id',
-    'resource-name',
-    'resource_name',
-    'integration-id',
-    'integration_id',
-    'widget-type',
-    'branch',
-    'commit-id',
-    'commit_id',
-    'profile-id',
-    'profile_id',
-    // Stack traces
-    'error.stack',
-    'exception.stacktrace',
-    // Auth/secrets
-    'auth_token',
-    'api_key',
-    'authorization',
-    'cookie',
-    'x-api-key',
-]);
+export const TIER_2_TRACE_CONTRACT = [
+    {
+        name: "HTTP GET *",
+        allowedAttributes: [
+            "http.method",
+            { name: "http.route", maxCardinality: 150 },
+            "http.status_code",
+            "http.response_content_length",
+            { name: "http.flavor", allowedValues: ["1.0", "1.1", "2.0", "3.0"] },
+        ],
+    },
+    {
+        name: "HTTP POST *",
+        allowedAttributes: [
+            "http.method",
+            { name: "http.route", maxCardinality: 150 },
+            "http.status_code",
+            "http.response_content_length",
+            "http.request_content_length",
+            { name: "http.flavor", allowedValues: ["1.0", "1.1", "2.0", "3.0"] },
+        ],
+    },
+    {
+        name: "HTTP PUT *",
+        allowedAttributes: [
+            "http.method",
+            { name: "http.route", maxCardinality: 150 },
+            "http.status_code",
+            "http.response_content_length",
+            "http.request_content_length",
+        ],
+    },
+    {
+        name: "HTTP DELETE *",
+        allowedAttributes: [
+            "http.method",
+            { name: "http.route", maxCardinality: 150 },
+            "http.status_code",
+            "http.response_content_length",
+        ],
+    },
+    {
+        name: "HTTP PATCH *",
+        allowedAttributes: [
+            "http.method",
+            { name: "http.route", maxCardinality: 150 },
+            "http.status_code",
+            "http.response_content_length",
+            "http.request_content_length",
+        ],
+    },
+    {
+        name: "request handler *",
+        allowedAttributes: [
+            "http.method",
+            { name: "http.route", maxCardinality: 150 },
+            "http.status_code",
+            "http.response_content_length",
+            "http.request_content_length",
+            { name: "http.flavor", allowedValues: ["1.0", "1.1", "2.0", "3.0"] },
+            "express.route",
+        ],
+    },
+    {
+        name: "WS SERVER *",
+        allowedAttributes: [
+            { name: "messaging.system", allowedValues: ["ws", "websocket"] },
+            { name: "messaging.destination_kind", allowedValues: ["websocket"] },
+            { name: "ws.handler", maxCardinality: 80 },
+        ],
+    },
+    {
+        name: "WS CLIENT *",
+        allowedAttributes: [
+            { name: "messaging.system", allowedValues: ["ws", "websocket"] },
+        ],
+    },
+    {
+        name: "WS HANDLER *",
+        allowedAttributes: [
+            { name: "messaging.system", allowedValues: ["ws", "websocket"] },
+            { name: "messaging.destination_kind", allowedValues: ["websocket"] },
+        ],
+    },
+    {
+        name: "api.execute",
+        alwaysSample: true,
+        allowedAttributes: [
+            { name: "view-mode", allowedValues: ["edit", "deployed", "preview"] },
+            {
+                name: "api.status",
+                allowedValues: ["success", "error", "timeout", "cancelled"],
+            },
+            { name: "api.type", allowedValues: ["api", "workflow", "scheduled_job"] },
+            { name: "api.step_count", type: "number" },
+            { name: "api.duration_ms", type: "number" },
+            { name: "remote", allowedValues: ["true", "false"] },
+            "otel.status_code",
+            "otel.status_description",
+        ],
+    },
+    {
+        name: "api.step",
+        allowedAttributes: [
+            { name: "step.type", maxCardinality: 50 },
+            { name: "step.status", allowedValues: ["success", "error"] },
+            { name: "step.duration_ms", type: "number" },
+            { name: "step.retry_count", type: "number" },
+            "otel.status_code",
+        ],
+    },
+    {
+        name: "api.block.*",
+        allowedAttributes: [
+            { name: "block.type", maxCardinality: 30 },
+            { name: "block.status", allowedValues: ["success", "error"] },
+        ],
+    },
+    {
+        name: "plugin.*",
+        allowedAttributes: [
+            { name: "plugin.name", maxCardinality: 80 },
+            {
+                name: "plugin.event",
+                allowedValues: ["execute", "test", "metadata", "pre_delete"],
+            },
+            { name: "plugin.result", allowedValues: ["succeeded", "failed"] },
+            { name: "plugin.duration_ms", type: "number" },
+            "otel.status_code",
+        ],
+    },
+    {
+        name: "db.*",
+        allowedAttributes: [
+            {
+                name: "db.system",
+                allowedValues: [
+                    "postgresql",
+                    "mysql",
+                    "mssql",
+                    "mongodb",
+                    "redis",
+                    "snowflake",
+                    "bigquery",
+                    "databricks",
+                    "dynamodb",
+                    "sqlite",
+                ],
+            },
+            {
+                name: "db.operation",
+                allowedValues: ["select", "insert", "update", "delete", "other"],
+            },
+            { name: "db.name", maxCardinality: 50 },
+            "otel.status_code",
+        ],
+    },
+    {
+        name: "llm.request",
+        allowedAttributes: [
+            {
+                name: "gen_ai.operation.name",
+                allowedValues: [
+                    "chat",
+                    "text_completion",
+                    "embeddings",
+                    "execute_tool",
+                    "invoke_agent",
+                    "generate_content",
+                ],
+            },
+            {
+                name: "gen_ai.system",
+                allowedValues: [
+                    "openai",
+                    "anthropic",
+                    "aws.bedrock",
+                    "azure.ai.openai",
+                    "azure.ai.inference",
+                    "gcp.gemini",
+                    "gcp.vertex_ai",
+                    "cohere",
+                    "mistral_ai",
+                    "deepseek",
+                    "groq",
+                ],
+            },
+            {
+                name: "gen_ai.provider.name",
+                allowedValues: [
+                    "openai",
+                    "anthropic",
+                    "aws.bedrock",
+                    "azure.ai.openai",
+                    "azure.ai.inference",
+                    "gcp.gemini",
+                    "gcp.vertex_ai",
+                    "cohere",
+                    "mistral_ai",
+                    "deepseek",
+                    "groq",
+                ],
+            },
+            { name: "gen_ai.request.model", maxCardinality: 50 },
+            { name: "gen_ai.response.model", maxCardinality: 50 },
+            "llm.provider",
+            "llm.model",
+            "llm.status",
+            {
+                name: "llm.error_category",
+                allowedValues: [
+                    "none",
+                    "rate_limit",
+                    "context_length",
+                    "content_filter",
+                    "quota",
+                    "network",
+                    "timeout",
+                    "auth_error",
+                    "api_error",
+                    "validation_error",
+                    "aborted",
+                    "unknown",
+                ],
+            },
+            "llm.duration_ms",
+            "gen_ai.usage.input_tokens",
+            "gen_ai.usage.output_tokens",
+            "llm.input_tokens",
+            "llm.output_tokens",
+            "llm.total_tokens",
+            "llm.reasoning_tokens",
+            "llm.cached_tokens",
+            "llm.cost_usd",
+            { name: "gen_ai.client.time_to_first_token", type: "number" },
+            { name: "llm.time_to_first_token_ms", type: "number" },
+            "gen_ai.response.finish_reasons",
+            "llm.finish_reason",
+            "otel.status_code",
+        ],
+    },
+    {
+        name: "llm.tool_call",
+        allowedAttributes: [
+            { name: "tool.name", maxCardinality: 50 },
+            { name: "tool.status", allowedValues: ["success", "error"] },
+            {
+                name: "tool.error_category",
+                allowedValues: [
+                    "none",
+                    "timeout",
+                    "execution_error",
+                    "validation_error",
+                    "permission_denied",
+                    "not_found",
+                    "unknown",
+                ],
+            },
+            { name: "tool.duration_ms", type: "number" },
+            "otel.status_code",
+        ],
+    },
+    {
+        name: "ai.streamText",
+        allowedAttributes: [
+            "llm.provider",
+            "llm.model",
+            "llm.total_tokens",
+            "llm.step_count",
+        ],
+    },
+    {
+        name: "ai.streamText.step",
+        allowedAttributes: [
+            { name: "step.number", type: "number" },
+            {
+                name: "step.type",
+                allowedValues: ["text", "tool_call", "thinking", "reasoning"],
+            },
+        ],
+    },
+    {
+        name: "clark.session",
+        allowedAttributes: [
+            "session.duration_ms",
+            "session.step_count",
+            "session.llm_call_count",
+            "session.tool_call_count",
+            "session.total_tokens",
+            {
+                name: "session.outcome",
+                allowedValues: ["success", "error", "aborted"],
+            },
+        ],
+    },
+    {
+        name: "clark.debug_loop",
+        allowedAttributes: [
+            { name: "loop.iteration", type: "number" },
+            {
+                name: "loop.reason",
+                allowedValues: ["error_recovery", "validation_failure", "retry"],
+            },
+            { name: "loop.duration_ms", type: "number" },
+        ],
+    },
+    {
+        name: "grpc.*",
+        allowedAttributes: [
+            { name: "rpc.system", allowedValues: ["grpc"] },
+            { name: "rpc.service", maxCardinality: 50 },
+            { name: "rpc.method", maxCardinality: 100 },
+            { name: "rpc.grpc.status_code", type: "number" },
+        ],
+    },
+    {
+        name: "kafka.*",
+        allowedAttributes: [
+            { name: "messaging.system", allowedValues: ["kafka"] },
+            { name: "messaging.destination", maxCardinality: 50 },
+            {
+                name: "messaging.operation",
+                allowedValues: ["publish", "receive", "process"],
+            },
+        ],
+    },
+    {
+        name: "redis.*",
+        allowedAttributes: [
+            { name: "db.system", allowedValues: ["redis"] },
+            { name: "db.operation", maxCardinality: 30 },
+        ],
+    },
+    {
+        name: "fetch",
+        allowedAttributes: [
+            "http.method",
+            "http.status_code",
+            { name: "http.host", maxCardinality: 200 },
+        ],
+    },
+    {
+        name: "schedule.*",
+        allowedAttributes: [
+            {
+                name: "schedule.type",
+                allowedValues: ["cron", "interval", "one_time"],
+            },
+            {
+                name: "schedule.status",
+                allowedValues: ["success", "error", "skipped"],
+            },
+        ],
+    },
+];
 /**
- * Attributes that should be HASHED (pseudonymized) in Tier 2 telemetry.
- * The Collector replaces these with SHA256 hashes for privacy.
- * Hashes enable aggregate analysis without exposing plaintext identifiers.
- *
- * Mapping:
- *   user-email, user.email, etc. → user.hash
- *   organization-id, organization_id → organization.hash
- *   application-id, application_id → application.hash
- *   session.id → session.hash
- *   enduser.id → enduser.pseudo.id
+ * Cloud trace contract: match-all span name ("*") so no spans are dropped by name.
+ * Attribute allowlist is not used when attributeAllowlistPassthrough is true.
  */
-export const TIER2_HASHED_ATTRIBUTES = new Set([
-    // User identity (hashed to user.hash)
-    'user-email',
-    'user.email',
-    'user_email',
-    'user.id',
-    'enduser.email',
-    // Organization identity (hashed to organization.hash)
-    'organization-id',
-    'organization_id',
-    // Application identity (hashed to application.hash)
-    'application-id',
-    'application_id',
-    // Session/enduser identity
-    'session.id',
-    'enduser.id',
-]);
+export const CLOUD_TRACE_CONTRACT = [
+    { name: "*", allowedAttributes: [] },
+];
 /**
- * Attributes that should be DROPPED entirely in Tier 2.
- * These are correlation IDs that don't provide operational value.
+ * Returns the trace contract (span definitions) for the given deployment type.
+ * Cloud: match-all so no traces are dropped by span name.
+ * Cloud-prem: Tier 2 contract (named spans only).
  */
-export const TIER2_DROPPED_ATTRIBUTES = new Set([
-    'correlation-id',
-    'correlation_id',
-    'request-id',
-    'request_id',
-    'trace-id',
-    'execution_id',
-    'binding_keys',
-]);
+export function getTraceContract(deploymentType) {
+    switch (deploymentType) {
+        case DeploymentTypeEnum.CLOUD:
+            return CLOUD_TRACE_CONTRACT;
+        case DeploymentTypeEnum.CLOUD_PREM:
+        default:
+            return TIER_2_TRACE_CONTRACT;
+    }
+}
+// ---------------------------------------------------------------------------
+// Forbidden / hashed / dropped attribute names (v0.2.0 JSON)
+// ---------------------------------------------------------------------------
+/** Forbidden in Tier 2 (forbiddenAttributes in contract). Collector strips these entirely. */
+export const FORBIDDEN_TIER_2_SPAN_ATTRIBUTES = [
+    "llmobs.input",
+    "llmobs.output",
+    "prompt",
+    "code",
+    "tool_input",
+    "tool_output",
+    "file_path",
+    "file_content",
+    "db.statement",
+    "db.query_text",
+    "db.query.text",
+    "http.request.body",
+    "http.response.body",
+    "url.full",
+    "url.query",
+    "http.url",
+    "http.target",
+    "user-email",
+    "user.email",
+    "user_email",
+    "enduser.email",
+    "api-name",
+    "api_name",
+    "resource-name",
+    "resource_name",
+    "widget-type",
+    "branch",
+    "error.stack",
+    "exception.stacktrace",
+    "auth_token",
+    "api_key",
+    "authorization",
+    "cookie",
+    "x-api-key",
+];
+/** Hashed (keyed HMAC) for Tier 2 (hashedAttributes in contract). */
+export const HASHED_TIER_2_SPAN_ATTRIBUTES = [];
+/** Dropped — high cardinality, no hash value (droppedAttributes in contract). */
+export const DROPPED_HIGH_CARDINALITY_ATTRIBUTES = ["binding_keys"];
+// ---------------------------------------------------------------------------
+// Set views (for lint, guardrails: fast .has() lookup)
+// ---------------------------------------------------------------------------
+export const TIER2_FORBIDDEN_ATTRIBUTES = new Set(FORBIDDEN_TIER_2_SPAN_ATTRIBUTES);
+export const TIER2_HASHED_ATTRIBUTES = new Set(HASHED_TIER_2_SPAN_ATTRIBUTES);
+export const TIER2_DROPPED_ATTRIBUTES = new Set(DROPPED_HIGH_CARDINALITY_ATTRIBUTES);
+// ---------------------------------------------------------------------------
+// Per-deployment attribute sets (for trace-sanitizer)
+// ---------------------------------------------------------------------------
+/** Empty set used for cloud (relaxed policy: no drop, no hash, no forbidden). */
+const EMPTY_ATTRIBUTE_SET = new Set();
 /**
- * Spans that should ALWAYS be sampled (never dropped by rate limiting).
+ * Returns the Tier 2 trace attribute sets and contract options for the given deployment type.
+ * Cloud: relaxed policy (no attributes dropped/hashed), match-all span names, pass-through attributes.
+ * Cloud-prem: full Tier 2 contract (forbidden/dropped/hashed), named spans only, pass-through attributes.
  */
-export const ALWAYS_SAMPLE_SPANS = new Set([
-    'api.execute',
-]);
+export function getTraceSanitizerAttributeSets(deploymentType) {
+    const spanDefinitions = getTraceContract(deploymentType);
+    const attributeAllowlistPassthrough = true;
+    switch (deploymentType) {
+        case DeploymentTypeEnum.CLOUD:
+            return {
+                forbiddenAttributes: EMPTY_ATTRIBUTE_SET,
+                droppedAttributes: EMPTY_ATTRIBUTE_SET,
+                hashedAttributes: EMPTY_ATTRIBUTE_SET,
+                spanDefinitions,
+                attributeAllowlistPassthrough,
+            };
+        case DeploymentTypeEnum.CLOUD_PREM:
+        default:
+            return {
+                forbiddenAttributes: TIER2_FORBIDDEN_ATTRIBUTES,
+                droppedAttributes: TIER2_DROPPED_ATTRIBUTES,
+                hashedAttributes: TIER2_HASHED_ATTRIBUTES,
+                spanDefinitions,
+                attributeAllowlistPassthrough,
+            };
+    }
+}
+// ---------------------------------------------------------------------------
+// Always-sample and value patterns (v0.2.0 samplingPolicy + lint-time)
+// ---------------------------------------------------------------------------
+/** Spans that should ALWAYS be sampled (samplingPolicy.alwaysSampleSpans in contract). */
+export const ALWAYS_SAMPLE_SPANS = new Set(["api.execute"]);
 /**
- * Patterns that indicate forbidden content in attribute values.
- * Used for secondary filtering when attribute names aren't explicit.
- *
- * IMPORTANT: Patterns should NOT use ^ and $ anchors so they match
- * secrets embedded anywhere in a string (e.g., in query params, headers).
+ * Patterns that indicate forbidden content in attribute values (e.g. secrets in strings).
+ * No ^/$ anchors so they match secrets embedded anywhere.
+ * It's not used by TraceSanitizer, only in guardrails.
  */
 export const FORBIDDEN_VALUE_PATTERNS = [
-    // JWT tokens (anywhere in string)
-    // Header (eyJ...) and payload (eyJ...) must be base64url encoded JSON
-    // Signature can be any length (even short for test tokens)
     /eyJ[A-Za-z0-9_-]{10,}\.eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]+/,
-    // API keys (sk-/pk- prefix patterns with word boundaries)
     /\b(sk|pk)-[a-zA-Z0-9]{32,}\b/,
-    // Bearer tokens (anywhere in string)
     /Bearer\s+[A-Za-z0-9._-]{20,}/,
-    // PEM blocks (anywhere in string)
     /-----BEGIN\s+(RSA\s+)?(PRIVATE|PUBLIC)\s+KEY-----/,
-    // AWS access key IDs
     /\bAKIA[A-Z0-9]{16}\b/,
-    // GitHub tokens
     /\b(ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{36,}\b/,
-    // Generic API key patterns (key=value or key:value with long alphanumeric)
     /\b(api[_-]?key|apikey|secret[_-]?key|access[_-]?token)[=:]\s*[A-Za-z0-9_-]{20,}\b/i,
 ];
-/**
- * Check if an attribute name is forbidden in Tier 2.
- */
+// ---------------------------------------------------------------------------
+// Helpers (for lint, guardrails)
+// ---------------------------------------------------------------------------
 export function isForbiddenAttribute(name) {
     return TIER2_FORBIDDEN_ATTRIBUTES.has(name);
 }
-/**
- * Check if an attribute should be hashed in Tier 2.
- */
 export function isHashedAttribute(name) {
     return TIER2_HASHED_ATTRIBUTES.has(name);
 }
-/**
- * Check if an attribute should be dropped in Tier 2.
- */
 export function isDroppedAttribute(name) {
     return TIER2_DROPPED_ATTRIBUTES.has(name);
 }
-/**
- * Check if a value contains forbidden patterns (like tokens, keys).
- */
 export function containsForbiddenPattern(value) {
-    if (typeof value !== 'string')
+    if (typeof value !== "string")
         return false;
-    return FORBIDDEN_VALUE_PATTERNS.some(pattern => pattern.test(value));
+    return FORBIDDEN_VALUE_PATTERNS.some((pattern) => pattern.test(value));
 }
-/**
- * Check if a span should always be sampled.
- */
 export function shouldAlwaysSample(spanName) {
     return ALWAYS_SAMPLE_SPANS.has(spanName);
 }