@senad-d/observme 0.1.0

package/src/semconv/attributes.ts

@@ -0,0 +1,279 @@
+export type AttributeKey = (typeof ALL_ATTRIBUTE_KEYS)[number];
+
+export const RESOURCE_ATTRIBUTES = {
+  SERVICE_NAME: "service.name",
+  SERVICE_NAMESPACE: "service.namespace",
+  SERVICE_VERSION: "service.version",
+  SERVICE_INSTANCE_ID: "service.instance.id",
+  TELEMETRY_SDK_NAME: "telemetry.sdk.name",
+  OBSERVME_VERSION: "observme.version",
+  OBSERVME_INSTANCE_ID: "observme.instance.id",
+  PI_AGENT_ID: "pi.agent.id",
+  PI_AGENT_PARENT_ID: "pi.agent.parent_id",
+  PI_AGENT_ROOT_ID: "pi.agent.root_id",
+  PI_AGENT_ROLE: "pi.agent.role",
+  PI_AGENT_DEPTH: "pi.agent.depth",
+  PI_CWD_HASH: "pi.cwd.hash",
+  PI_CWD_BASENAME: "pi.cwd.basename",
+  DEPLOYMENT_ENVIRONMENT_NAME: "deployment.environment.name",
+  OBSERVME_ENVIRONMENT: "observme.environment",
+  OBSERVME_TENANT_ID: "observme.tenant.id",
+  PI_WORKFLOW_ID: "pi.workflow.id",
+  PI_WORKFLOW_ROOT_AGENT_ID: "pi.workflow.root_agent_id",
+  PI_USER_HASH: "pi.user.hash",
+  PI_PROJECT_NAME: "pi.project.name",
+} as const;
+
+export const SESSION_ATTRIBUTES = {
+  PI_SESSION_ID: "pi.session.id",
+  PI_SESSION_NAME: "pi.session.name",
+  PI_SESSION_CWD_HASH: "pi.session.cwd_hash",
+  PI_SESSION_PARENT_SESSION_HASH: "pi.session.parent_session_hash",
+  PI_SESSION_PERSISTED: "pi.session.persisted",
+  PI_SESSION_FILE_HASH: "pi.session.file_hash",
+  PI_SESSION_VERSION: "pi.session.version",
+  PI_MODEL_PROVIDER_CURRENT: "pi.model.provider.current",
+  PI_MODEL_ID_CURRENT: "pi.model.id.current",
+  PI_THINKING_LEVEL_CURRENT: "pi.thinking.level.current",
+} as const;
+
+export const WORKFLOW_ATTRIBUTES = {
+  PI_WORKFLOW_DURATION_MS: "pi.workflow.duration_ms",
+  PI_WORKFLOW_STATUS: "pi.workflow.status",
+} as const;
+
+export const COMMON_SPAN_ATTRIBUTES = {
+  PI_SESSION_ID: "pi.session.id",
+  PI_WORKFLOW_ID: "pi.workflow.id",
+  PI_WORKFLOW_ROOT_AGENT_ID: "pi.workflow.root_agent_id",
+  PI_AGENT_ID: "pi.agent.id",
+  PI_AGENT_PARENT_ID: "pi.agent.parent_id",
+  PI_AGENT_ROOT_ID: "pi.agent.root_id",
+  PI_AGENT_RUN_ID: "pi.agent.run.id",
+  PI_ENTRY_ID: "pi.entry.id",
+  PI_ENTRY_PARENT_ID: "pi.entry.parent_id",
+  PI_ENTRY_TYPE: "pi.entry.type",
+  OBSERVME_CAPTURE_PROMPTS: "observme.capture.prompts",
+  OBSERVME_CAPTURE_RESPONSES: "observme.capture.responses",
+  OBSERVME_CAPTURE_TOOL_ARGUMENTS: "observme.capture.tool_arguments",
+  OBSERVME_REDACTION_ENABLED: "observme.redaction.enabled",
+  OBSERVME_SEMCONV_VERSION: "observme.semconv.version",
+  OBSERVME_REPLAYED: "observme.replayed",
+  OBSERVME_EVICTED: "observme.evicted",
+  OBSERVME_TRUNCATED: "observme.truncated",
+  OBSERVME_ORIGINAL_LENGTH: "observme.original_length",
+} as const;
+
+export const AGENT_LINEAGE_ATTRIBUTES = {
+  PI_AGENT_CAPABILITY: "pi.agent.capability",
+  PI_AGENT_ORPHANED: "pi.agent.orphaned",
+} as const;
+
+export const AGENT_RUN_ATTRIBUTES = {
+  PI_AGENT_ID: "pi.agent.id",
+  PI_AGENT_PARENT_ID: "pi.agent.parent_id",
+  PI_AGENT_ROOT_ID: "pi.agent.root_id",
+  PI_AGENT_ROLE: "pi.agent.role",
+  PI_AGENT_DEPTH: "pi.agent.depth",
+  PI_AGENT_RUN_ID: "pi.agent.run.id",
+  PI_AGENT_RUN_INDEX: "pi.agent.run.index",
+  PI_AGENT_RUN_SOURCE: "pi.agent.run.source",
+  PI_AGENT_RUN_PROMPT_HASH: "pi.agent.run.prompt.hash",
+  PI_AGENT_RUN_PROMPT_LENGTH: "pi.agent.run.prompt.length",
+  GEN_AI_AGENT_ID: "gen_ai.agent.id",
+  GEN_AI_AGENT_NAME: "gen_ai.agent.name",
+  GEN_AI_AGENT_VERSION: "gen_ai.agent.version",
+} as const;
+
+export const AGENT_SPAWN_ATTRIBUTES = {
+  PI_AGENT_SPAWN_ID: "pi.agent.spawn.id",
+  PI_AGENT_SPAWN_TYPE: "pi.agent.spawn.type",
+  PI_AGENT_SPAWN_REASON: "pi.agent.spawn.reason",
+  PI_AGENT_SPAWN_OUTCOME: "pi.agent.spawn.outcome",
+  PI_AGENT_SPAWN_TOOL_CALL_ID: "pi.agent.spawn.tool_call_id",
+  PI_AGENT_SPAWN_COMMAND_HASH: "pi.agent.spawn.command.hash",
+  PI_AGENT_CHILD_ID: "pi.agent.child.id",
+  PI_AGENT_CHILD_COUNT: "pi.agent.child.count",
+  PI_AGENT_CHILDREN_ACTIVE: "pi.agent.children.active",
+  PI_AGENT_PARENT_ID: "pi.agent.parent_id",
+  PI_AGENT_ROOT_ID: "pi.agent.root_id",
+  PI_WORKFLOW_ID: "pi.workflow.id",
+  PI_WORKFLOW_ROOT_AGENT_ID: "pi.workflow.root_agent_id",
+  PI_AGENT_DEPTH: "pi.agent.depth",
+  PI_SESSION_ID: "pi.session.id",
+  PI_AGENT_SPAWN_TRACE_CONTEXT_PROPAGATED: "pi.agent.spawn.trace_context_propagated",
+} as const;
+
+export const AGENT_WAIT_JOIN_ATTRIBUTES = {
+  PI_WORKFLOW_ID: "pi.workflow.id",
+  PI_AGENT_ID: "pi.agent.id",
+  PI_AGENT_CHILD_ID: "pi.agent.child.id",
+  PI_AGENT_SPAWN_ID: "pi.agent.spawn.id",
+  PI_AGENT_WAIT_REASON: "pi.agent.wait.reason",
+  PI_AGENT_JOIN_STATUS: "pi.agent.join.status",
+  PI_AGENT_CHILD_STATUS: "pi.agent.child.status",
+  PI_AGENT_FAILURE_PROPAGATED: "pi.agent.failure.propagated",
+  PI_AGENT_CHILDREN_ACTIVE: "pi.agent.children.active",
+  PI_AGENT_CHILD_COUNT: "pi.agent.child.count",
+} as const;
+
+export const TURN_ATTRIBUTES = {
+  PI_TURN_ID: "pi.turn.id",
+  PI_TURN_INDEX: "pi.turn.index",
+  PI_TURN_BRANCH_PATH_HASH: "pi.turn.branch_path_hash",
+  PI_TURN_USER_MESSAGE_HASH: "pi.turn.user_message.hash",
+  PI_TURN_USER_MESSAGE_LENGTH: "pi.turn.user_message.length",
+  PI_TURN_USER_MESSAGE_IMAGE_COUNT: "pi.turn.user_message.image_count",
+  PI_MODEL_PROVIDER_CURRENT: "pi.model.provider.current",
+  PI_MODEL_ID_CURRENT: "pi.model.id.current",
+} as const;
+
+export const LLM_ATTRIBUTES = {
+  GEN_AI_OPERATION_NAME: "gen_ai.operation.name",
+  GEN_AI_PROVIDER_NAME: "gen_ai.provider.name",
+  GEN_AI_REQUEST_MODEL: "gen_ai.request.model",
+  GEN_AI_RESPONSE_MODEL: "gen_ai.response.model",
+  GEN_AI_RESPONSE_ID: "gen_ai.response.id",
+  GEN_AI_RESPONSE_FINISH_REASONS: "gen_ai.response.finish_reasons",
+  GEN_AI_REQUEST_TEMPERATURE: "gen_ai.request.temperature",
+  GEN_AI_REQUEST_MAX_TOKENS: "gen_ai.request.max_tokens",
+  GEN_AI_USAGE_INPUT_TOKENS: "gen_ai.usage.input_tokens",
+  GEN_AI_USAGE_OUTPUT_TOKENS: "gen_ai.usage.output_tokens",
+  GEN_AI_USAGE_CACHE_READ_INPUT_TOKENS: "gen_ai.usage.cache_read.input_tokens",
+  GEN_AI_USAGE_CACHE_CREATION_INPUT_TOKENS: "gen_ai.usage.cache_creation.input_tokens",
+  GEN_AI_USAGE_REASONING_OUTPUT_TOKENS: "gen_ai.usage.reasoning.output_tokens",
+  GEN_AI_CONVERSATION_ID: "gen_ai.conversation.id",
+  ERROR_TYPE: "error.type",
+  PI_LLM_API: "pi.llm.api",
+  PI_LLM_REQUEST_THINKING_LEVEL: "pi.llm.request.thinking_level",
+  PI_LLM_REQUEST_MESSAGE_COUNT: "pi.llm.request.message_count",
+  PI_LLM_REQUEST_TOOL_SCHEMA_COUNT: "pi.llm.request.tool_schema_count",
+  PI_LLM_REQUEST_INPUT_CHARS: "pi.llm.request.input_chars",
+  PI_LLM_REQUEST_ID: "pi.llm.request.id",
+  PI_LLM_STOP_REASON: "pi.llm.stop_reason",
+  PI_LLM_ERROR_MESSAGE_HASH: "pi.llm.error_message_hash",
+  PI_LLM_USAGE_TOTAL_TOKENS: "pi.llm.usage.total_tokens",
+  PI_LLM_USAGE_CACHE_WRITE_1H_TOKENS: "pi.llm.usage.cache_write_1h_tokens",
+  PI_LLM_COST_INPUT_USD: "pi.llm.cost.input_usd",
+  PI_LLM_COST_OUTPUT_USD: "pi.llm.cost.output_usd",
+  PI_LLM_COST_CACHE_READ_USD: "pi.llm.cost.cache_read_usd",
+  PI_LLM_COST_CACHE_WRITE_USD: "pi.llm.cost.cache_write_usd",
+  PI_LLM_COST_TOTAL_USD: "pi.llm.cost.total_usd",
+  PI_LLM_TOOL_CALL_COUNT: "pi.llm.tool_call_count",
+  GEN_AI_INPUT_MESSAGES: "gen_ai.input.messages",
+  GEN_AI_OUTPUT_MESSAGES: "gen_ai.output.messages",
+  PI_LLM_PROMPT_REDACTED: "pi.llm.prompt.redacted",
+  PI_LLM_RESPONSE_REDACTED: "pi.llm.response.redacted",
+  PI_LLM_THINKING_REDACTED: "pi.llm.thinking.redacted",
+  PI_LLM_CONTENT_KIND: "pi.llm.content.kind",
+} as const;
+
+export const MESSAGE_ATTRIBUTES = {
+  PI_MESSAGE_ROLE: "pi.message.role",
+  PI_MESSAGE_CONTENT_LENGTH: "pi.message.content_length",
+} as const;
+
+export const TOOL_ATTRIBUTES = {
+  PI_TOOL_CALL_ID: "pi.tool.call.id",
+  PI_TOOL_NAME: "pi.tool.name",
+  PI_TOOL_CATEGORY: "pi.tool.category",
+  PI_TOOL_ARGUMENTS_HASH: "pi.tool.arguments.hash",
+  PI_TOOL_ARGUMENTS_SIZE: "pi.tool.arguments.size",
+  PI_TOOL_RESULT_SIZE: "pi.tool.result.size",
+  PI_TOOL_RESULT_HASH: "pi.tool.result.hash",
+  PI_TOOL_SUCCESS: "pi.tool.success",
+  PI_TOOL_ERROR: "pi.tool.error",
+  PI_TOOL_ERROR_CLASS: "pi.tool.error_class",
+  GEN_AI_TOOL_CALL_ID: "gen_ai.tool.call.id",
+  GEN_AI_TOOL_NAME: "gen_ai.tool.name",
+  GEN_AI_TOOL_TYPE: "gen_ai.tool.type",
+  PI_TOOL_ARGUMENTS_REDACTED: "pi.tool.arguments.redacted",
+  PI_TOOL_RESULT_REDACTED: "pi.tool.result.redacted",
+  GEN_AI_TOOL_CALL_ARGUMENTS: "gen_ai.tool.call.arguments",
+  GEN_AI_TOOL_CALL_RESULT: "gen_ai.tool.call.result",
+} as const;
+
+export const BASH_ATTRIBUTES = {
+  PI_BASH_COMMAND_HASH: "pi.bash.command.hash",
+  PI_BASH_COMMAND_REDACTED: "pi.bash.command.redacted",
+  PI_BASH_EXIT_CODE: "pi.bash.exit_code",
+  PI_BASH_CANCELLED: "pi.bash.cancelled",
+  PI_BASH_TRUNCATED: "pi.bash.truncated",
+  PI_BASH_OUTPUT_SIZE: "pi.bash.output.size",
+  PI_BASH_OUTPUT_HASH: "pi.bash.output.hash",
+  PI_BASH_OUTPUT_REDACTED: "pi.bash.output.redacted",
+  PI_BASH_FULL_OUTPUT_PATH_PRESENT: "pi.bash.full_output_path_present",
+  PI_BASH_EXCLUDE_FROM_CONTEXT: "pi.bash.exclude_from_context",
+} as const;
+
+export const BRANCH_ATTRIBUTES = {
+  PI_BRANCH_FROM_ID: "pi.branch.from_id",
+  PI_BRANCH_TO_ID: "pi.branch.to_id",
+  PI_BRANCH_COMMON_ANCESTOR_ID: "pi.branch.common_ancestor_id",
+  PI_BRANCH_PATH_HASH: "pi.branch.path_hash",
+  PI_LEAF_ID: "pi.leaf.id",
+  PI_BRANCH_SUMMARY_HASH: "pi.branch.summary.hash",
+  PI_BRANCH_SUMMARY_LENGTH: "pi.branch.summary.length",
+  PI_BRANCH_FROM_HOOK: "pi.branch.from_hook",
+  PI_BRANCH_READ_FILES_COUNT: "pi.branch.read_files_count",
+  PI_BRANCH_MODIFIED_FILES_COUNT: "pi.branch.modified_files_count",
+} as const;
+
+export const COMPACTION_ATTRIBUTES = {
+  PI_COMPACTION_FIRST_KEPT_ENTRY_ID: "pi.compaction.first_kept_entry_id",
+  PI_COMPACTION_TOKENS_BEFORE: "pi.compaction.tokens_before",
+  PI_COMPACTION_SUMMARY_HASH: "pi.compaction.summary.hash",
+  PI_COMPACTION_SUMMARY_LENGTH: "pi.compaction.summary.length",
+  PI_COMPACTION_FROM_HOOK: "pi.compaction.from_hook",
+  PI_COMPACTION_REASON: "pi.compaction.reason",
+  PI_COMPACTION_WILL_RETRY: "pi.compaction.will_retry",
+  PI_COMPACTION_READ_FILES_COUNT: "pi.compaction.read_files_count",
+  PI_COMPACTION_MODIFIED_FILES_COUNT: "pi.compaction.modified_files_count",
+} as const;
+
+export const CONFIG_ATTRIBUTES = {
+  OBSERVME_CONFIG_SOURCE: "observme.config.source",
+  OBSERVME_CONFIG_REJECTION_ISSUE_CODES: "observme.config.rejection.issue_codes",
+  OBSERVME_CONFIG_REJECTION_ISSUE_COUNT: "observme.config.rejection.issue_count",
+} as const;
+
+export const LOG_ATTRIBUTES = {
+  EVENT_NAME: "event.name",
+  EVENT_CATEGORY: "event.category",
+  PI_SESSION_ID: "pi.session.id",
+  PI_WORKFLOW_ID: "pi.workflow.id",
+  PI_WORKFLOW_ROOT_AGENT_ID: "pi.workflow.root_agent_id",
+  PI_AGENT_ID: "pi.agent.id",
+  PI_AGENT_PARENT_ID: "pi.agent.parent_id",
+  PI_AGENT_ROOT_ID: "pi.agent.root_id",
+  PI_AGENT_RUN_ID: "pi.agent.run.id",
+  PI_TURN_ID: "pi.turn.id",
+  TRACE_ID: "trace_id",
+  SPAN_ID: "span_id",
+  SEVERITY: "severity",
+  ERROR_TYPE: "error.type",
+} as const;
+
+export const ATTRIBUTE_GROUPS = {
+  RESOURCE_ATTRIBUTES,
+  SESSION_ATTRIBUTES,
+  WORKFLOW_ATTRIBUTES,
+  COMMON_SPAN_ATTRIBUTES,
+  AGENT_LINEAGE_ATTRIBUTES,
+  AGENT_RUN_ATTRIBUTES,
+  AGENT_SPAWN_ATTRIBUTES,
+  AGENT_WAIT_JOIN_ATTRIBUTES,
+  TURN_ATTRIBUTES,
+  LLM_ATTRIBUTES,
+  MESSAGE_ATTRIBUTES,
+  TOOL_ATTRIBUTES,
+  BASH_ATTRIBUTES,
+  BRANCH_ATTRIBUTES,
+  COMPACTION_ATTRIBUTES,
+  CONFIG_ATTRIBUTES,
+  LOG_ATTRIBUTES,
+} as const;
+
+export const ALL_ATTRIBUTE_KEYS = [
+  ...new Set(Object.values(ATTRIBUTE_GROUPS).flatMap(group => Object.values(group))),
+].sort((left, right) => left.localeCompare(right));

package/src/semconv/metrics.ts

@@ -0,0 +1,146 @@
+export const OBSERVME_COUNTER_METRIC_NAMES = {
+  SESSIONS_STARTED_TOTAL: "observme_sessions_started_total",
+  SESSIONS_SHUTDOWN_TOTAL: "observme_sessions_shutdown_total",
+  WORKFLOWS_STARTED_TOTAL: "observme_workflows_started_total",
+  WORKFLOWS_COMPLETED_TOTAL: "observme_workflows_completed_total",
+  WORKFLOW_ERRORS_TOTAL: "observme_workflow_errors_total",
+  AGENT_RUNS_TOTAL: "observme_agent_runs_total",
+  AGENT_RUN_ERRORS_TOTAL: "observme_agent_run_errors_total",
+  SUBAGENTS_SPAWNED_TOTAL: "observme_subagents_spawned_total",
+  SUBAGENT_SPAWN_FAILURES_TOTAL: "observme_subagent_spawn_failures_total",
+  ORPHAN_AGENTS_TOTAL: "observme_orphan_agents_total",
+  TRACE_CONTEXT_PROPAGATION_FAILURES_TOTAL: "observme_trace_context_propagation_failures_total",
+  CHILD_AGENT_FAILURES_TOTAL: "observme_child_agent_failures_total",
+  PARENT_RECOVERED_FROM_CHILD_FAILURE_TOTAL: "observme_parent_recovered_from_child_failure_total",
+  TURNS_STARTED_TOTAL: "observme_turns_started_total",
+  TURNS_COMPLETED_TOTAL: "observme_turns_completed_total",
+  LLM_REQUESTS_TOTAL: "observme_llm_requests_total",
+  LLM_ERRORS_TOTAL: "observme_llm_errors_total",
+  TOOL_CALLS_TOTAL: "observme_tool_calls_total",
+  TOOL_FAILURES_TOTAL: "observme_tool_failures_total",
+  BASH_EXECUTIONS_TOTAL: "observme_bash_executions_total",
+  BASH_FAILURES_TOTAL: "observme_bash_failures_total",
+  MODEL_CHANGES_TOTAL: "observme_model_changes_total",
+  THINKING_LEVEL_CHANGES_TOTAL: "observme_thinking_level_changes_total",
+  COMPACTIONS_TOTAL: "observme_compactions_total",
+  BRANCHES_TOTAL: "observme_branches_total",
+  TELEMETRY_DROPPED_TOTAL: "observme_telemetry_dropped_total",
+  EXPORT_ERRORS_TOTAL: "observme_export_errors_total",
+  REDACTION_FAILURES_TOTAL: "observme_redaction_failures_total",
+  EVENTS_OBSERVED_TOTAL: "observme_events_observed_total",
+  HANDLER_ERRORS_TOTAL: "observme_handler_errors_total",
+} as const;
+
+export const OBSERVME_TOKEN_COST_COUNTER_METRIC_NAMES = {
+  LLM_INPUT_TOKENS_TOTAL: "observme_llm_input_tokens_total",
+  LLM_OUTPUT_TOKENS_TOTAL: "observme_llm_output_tokens_total",
+  LLM_CACHE_READ_TOKENS_TOTAL: "observme_llm_cache_read_tokens_total",
+  LLM_CACHE_WRITE_TOKENS_TOTAL: "observme_llm_cache_write_tokens_total",
+  LLM_CACHE_WRITE_1H_TOKENS_TOTAL: "observme_llm_cache_write_1h_tokens_total",
+  LLM_REASONING_TOKENS_TOTAL: "observme_llm_reasoning_tokens_total",
+  LLM_TOTAL_TOKENS_TOTAL: "observme_llm_total_tokens_total",
+  LLM_COST_USD_TOTAL: "observme_llm_cost_usd_total",
+} as const;
+
+export const OBSERVME_HISTOGRAM_METRIC_NAMES = {
+  WORKFLOW_DURATION_MS: "observme_workflow_duration_ms",
+  AGENT_RUN_DURATION_MS: "observme_agent_run_duration_ms",
+  AGENT_LIFETIME_DURATION_MS: "observme_agent_lifetime_duration_ms",
+  SUBAGENT_SPAWN_DURATION_MS: "observme_subagent_spawn_duration_ms",
+  AGENT_WAIT_DURATION_MS: "observme_agent_wait_duration_ms",
+  AGENT_JOIN_DURATION_MS: "observme_agent_join_duration_ms",
+  AGENT_TREE_DEPTH: "observme_agent_tree_depth",
+  AGENT_TREE_WIDTH: "observme_agent_tree_width",
+  AGENT_FANOUT_COUNT: "observme_agent_fanout_count",
+  TURN_DURATION_MS: "observme_turn_duration_ms",
+  LLM_REQUEST_DURATION_MS: "observme_llm_request_duration_ms",
+  TOOL_DURATION_MS: "observme_tool_duration_ms",
+  BASH_DURATION_MS: "observme_bash_duration_ms",
+  COMPACTION_TOKENS_BEFORE: "observme_compaction_tokens_before",
+  PROMPT_SIZE_CHARS: "observme_prompt_size_chars",
+  RESPONSE_SIZE_CHARS: "observme_response_size_chars",
+  TOOL_RESULT_SIZE_CHARS: "observme_tool_result_size_chars",
+  HANDLER_DURATION_MS: "observme_handler_duration_ms",
+} as const;
+
+export const OBSERVME_GAUGE_METRIC_NAMES = {
+  ACTIVE_SPANS: "observme_active_spans",
+  ACTIVE_AGENTS: "observme_active_agents",
+} as const;
+
+export const OFFICIAL_GENAI_METRIC_NAMES = {
+  CLIENT_TOKEN_USAGE: "gen_ai.client.token.usage",
+  CLIENT_OPERATION_DURATION: "gen_ai.client.operation.duration",
+} as const;
+
+export const LOG_EVENT_NAMES = {
+  CONFIG_REJECTED: "config.rejected",
+  SESSION_STARTED: "session.started",
+  SESSION_NAMED: "session.named",
+  SESSION_SHUTDOWN: "session.shutdown",
+  SESSION_ERROR: "session.error",
+  SESSION_DUPLICATE_START: "session.duplicate_start",
+  WORKFLOW_STARTED: "workflow.started",
+  WORKFLOW_COMPLETED: "workflow.completed",
+  WORKFLOW_FAILED: "workflow.failed",
+  AGENT_RUN_STARTED: "agent.run.started",
+  AGENT_RUN_COMPLETED: "agent.run.completed",
+  AGENT_RUN_FAILED: "agent.run.failed",
+  AGENT_SPAWN_STARTED: "agent.spawn.started",
+  AGENT_SPAWN_COMPLETED: "agent.spawn.completed",
+  AGENT_SPAWN_FAILED: "agent.spawn.failed",
+  AGENT_WAIT_STARTED: "agent.wait.started",
+  AGENT_WAIT_COMPLETED: "agent.wait.completed",
+  AGENT_JOIN_STARTED: "agent.join.started",
+  AGENT_JOIN_COMPLETED: "agent.join.completed",
+  AGENT_ORPHANED: "agent.orphaned",
+  TRACE_CONTEXT_PROPAGATION_FAILED: "trace_context.propagation_failed",
+  TURN_STARTED: "turn.started",
+  TURN_COMPLETED: "turn.completed",
+  LLM_REQUEST_STARTED: "llm.request.started",
+  LLM_REQUEST_COMPLETED: "llm.request.completed",
+  LLM_REQUEST_FAILED: "llm.request.failed",
+  LLM_PROMPT_CAPTURED: "llm.prompt.captured",
+  LLM_RESPONSE_CAPTURED: "llm.response.captured",
+  LLM_THINKING_CAPTURED: "llm.thinking.captured",
+  MESSAGE_REPLAYED: "message.replayed",
+  TOOL_CALL_STARTED: "tool.call.started",
+  TOOL_CALL_COMPLETED: "tool.call.completed",
+  TOOL_CALL_FAILED: "tool.call.failed",
+  TOOL_ERROR_CAPTURED: "tool.error.captured",
+  BASH_COMPLETED: "bash.completed",
+  MODEL_CHANGED: "model.changed",
+  THINKING_CHANGED: "thinking.changed",
+  BRANCH_CREATED: "branch.created",
+  COMPACTION_CREATED: "compaction.created",
+  REDACTION_FAILED: "redaction.failed",
+  EXPORT_FAILED: "export.failed",
+  HANDLER_FAILED: "handler.failed",
+  TELEMETRY_DROPPED: "telemetry.dropped",
+} as const;
+
+export const OBSERVME_METRIC_NAME_GROUPS = {
+  COUNTERS: OBSERVME_COUNTER_METRIC_NAMES,
+  TOKEN_COST_COUNTERS: OBSERVME_TOKEN_COST_COUNTER_METRIC_NAMES,
+  HISTOGRAMS: OBSERVME_HISTOGRAM_METRIC_NAMES,
+  GAUGES: OBSERVME_GAUGE_METRIC_NAMES,
+} as const;
+
+export const ALL_OBSERVME_METRIC_NAMES = [
+  ...new Set(Object.values(OBSERVME_METRIC_NAME_GROUPS).flatMap(group => Object.values(group))),
+].sort((left, right) => left.localeCompare(right));
+
+export const ALL_OFFICIAL_GENAI_METRIC_NAMES = Object.values(OFFICIAL_GENAI_METRIC_NAMES).sort((left, right) =>
+  left.localeCompare(right),
+);
+
+export const ALL_METRIC_NAMES = [...ALL_OBSERVME_METRIC_NAMES, ...ALL_OFFICIAL_GENAI_METRIC_NAMES].sort((left, right) =>
+  left.localeCompare(right),
+);
+
+export const ALL_LOG_EVENT_NAMES = Object.values(LOG_EVENT_NAMES).sort((left, right) => left.localeCompare(right));
+
+export type ObservMeMetricName = (typeof ALL_OBSERVME_METRIC_NAMES)[number];
+export type OfficialGenAiMetricName = (typeof ALL_OFFICIAL_GENAI_METRIC_NAMES)[number];
+export type MetricName = (typeof ALL_METRIC_NAMES)[number];
+export type LogEventName = (typeof ALL_LOG_EVENT_NAMES)[number];

package/src/semconv/spans.ts

@@ -0,0 +1,19 @@
+export const SPAN_NAMES = {
+  PI_SESSION: "pi.session",
+  PI_AGENT_RUN: "pi.agent.run",
+  PI_AGENT_SPAWN: "pi.agent.spawn",
+  PI_AGENT_WAIT: "pi.agent.wait",
+  PI_AGENT_JOIN: "pi.agent.join",
+  PI_TURN: "pi.turn",
+  PI_LLM_REQUEST: "pi.llm.request",
+  PI_TOOL_CALL: "pi.tool.call",
+  PI_BASH_EXECUTION: "pi.bash.execution",
+  PI_COMPACTION: "pi.compaction",
+  PI_BRANCH: "pi.branch",
+  PI_MODEL_CHANGE: "pi.model.change",
+  PI_THINKING_CHANGE: "pi.thinking.change",
+} as const;
+
+export const ALL_SPAN_NAMES = Object.values(SPAN_NAMES).sort((left, right) => left.localeCompare(right));
+
+export type SpanName = (typeof ALL_SPAN_NAMES)[number];

package/src/semconv/values.ts

@@ -0,0 +1,13 @@
+export const SUBAGENT_SPAWN_REASON_VALUES = [
+  "delegated_task",
+  "parallel_search",
+  "review",
+  "tool_wrapper",
+  "unknown",
+] as const;
+
+export type SubagentSpawnReason = (typeof SUBAGENT_SPAWN_REASON_VALUES)[number];
+
+export const AGENT_WAIT_REASON_VALUES = ["dependency", "rate_limit", "child_running", "unknown"] as const;
+
+export type AgentWaitReason = (typeof AGENT_WAIT_REASON_VALUES)[number];

package/src/util/bounded-map.ts

@@ -0,0 +1,97 @@
+export interface BoundedMapEviction<K, V> {
+  readonly key: K;
+  readonly value: V;
+  readonly reason: "max_size_exceeded";
+}
+
+export interface BoundedMapOptions<K, V> {
+  readonly maxSize: number;
+  readonly onEvict?: (eviction: BoundedMapEviction<K, V>) => void;
+  readonly entries?: Iterable<readonly [K, V]>;
+}
+
+export class BoundedMap<K, V> implements Iterable<[K, V]> {
+  readonly #maxSize: number;
+  readonly #entries = new Map<K, V>();
+  readonly #onEvict?: (eviction: BoundedMapEviction<K, V>) => void;
+
+  constructor(options: BoundedMapOptions<K, V>) {
+    assertValidMaxSize(options.maxSize);
+    this.#maxSize = options.maxSize;
+    this.#onEvict = options.onEvict;
+
+    if (options.entries) this.setMany(options.entries);
+  }
+
+  get maxSize(): number {
+    return this.#maxSize;
+  }
+
+  get size(): number {
+    return this.#entries.size;
+  }
+
+  get(key: K): V | undefined {
+    return this.#entries.get(key);
+  }
+
+  has(key: K): boolean {
+    return this.#entries.has(key);
+  }
+
+  set(key: K, value: V): this {
+    this.#entries.set(key, value);
+    this.evictOldestEntriesOverLimit();
+    return this;
+  }
+
+  setMany(entries: Iterable<readonly [K, V]>): this {
+    for (const [key, value] of entries) this.set(key, value);
+    return this;
+  }
+
+  delete(key: K): boolean {
+    return this.#entries.delete(key);
+  }
+
+  clear(): void {
+    this.#entries.clear();
+  }
+
+  keys(): MapIterator<K> {
+    return this.#entries.keys();
+  }
+
+  values(): MapIterator<V> {
+    return this.#entries.values();
+  }
+
+  entries(): MapIterator<[K, V]> {
+    return this.#entries.entries();
+  }
+
+  toMap(): Map<K, V> {
+    return new Map(this.#entries);
+  }
+
+  [Symbol.iterator](): MapIterator<[K, V]> {
+    return this.entries();
+  }
+
+  private evictOldestEntriesOverLimit(): void {
+    while (this.#entries.size > this.#maxSize) this.evictOldestEntry();
+  }
+
+  private evictOldestEntry(): void {
+    const oldestEntry = this.#entries.entries().next().value;
+    if (!oldestEntry) return;
+
+    const [key, value] = oldestEntry;
+    this.#entries.delete(key);
+    this.#onEvict?.({ key, value, reason: "max_size_exceeded" });
+  }
+}
+
+export function assertValidMaxSize(maxSize: number): void {
+  if (!Number.isInteger(maxSize) || maxSize < 1) throw new Error("BoundedMap maxSize must be a positive integer");
+}

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2023",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "noEmit": true,
+    "allowImportingTsExtensions": true,
+    "types": ["node"]
+  },
+  "include": ["src/**/*.ts"]
+}