iac-code 0.1.0__py3-none-any.whl

iac_code/services/telemetry/client.py

@@ -0,0 +1,330 @@
+"""TelemetryClient — top-level facade that wires all components."""
+
+from __future__ import annotations
+
+import logging
+import os
+from pathlib import Path
+from typing import Any
+
+from opentelemetry._logs import set_logger_provider
+from opentelemetry.exporter.otlp.proto.http._log_exporter import OTLPLogExporter
+from opentelemetry.exporter.otlp.proto.http.metric_exporter import OTLPMetricExporter
+from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+from opentelemetry.sdk._logs import LoggerProvider
+from opentelemetry.sdk._logs.export import BatchLogRecordProcessor
+from opentelemetry.sdk.metrics import MeterProvider
+from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader
+from opentelemetry.sdk.resources import Resource
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor
+
+from iac_code.config import get_config_dir, get_settings_path
+from iac_code.services.telemetry.attributes import AttributeBuilder
+from iac_code.services.telemetry.config import is_telemetry_disabled
+from iac_code.services.telemetry.events import EventEmitter
+from iac_code.services.telemetry.fallback import FallbackStore
+from iac_code.services.telemetry.identity import Identity
+from iac_code.services.telemetry.metrics import MetricsRegistry
+from iac_code.services.telemetry.names import Events
+from iac_code.services.telemetry.sink import AnalyticsSink
+from iac_code.services.telemetry.tracing import SpanFactory
+
+log = logging.getLogger(__name__)
+
+_METRICS_EXPORT_INTERVAL_MS = 60_000
+_EVENTS_BATCH_DELAY_MS = 10_000
+_EVENTS_BATCH_MAX_SIZE = 200
+_FLUSH_TIMEOUT_MS = 2_000
+
+_SERVICE_NAME = "iac-code"
+
+
+class TelemetryClient:
+    """Top-level facade. Assembles all components and manages lifecycle."""
+
+    # ------------------------------------------------------------------
+    # Built-in default backend configuration
+    # ------------------------------------------------------------------
+    # Initial target: Aliyun ARMS (APM tracing). Users override via
+    # IAC_CODE_TELEMETRY_* environment variables. Each signal has its own
+    # endpoint because ARMS uses different URL paths per signal (unlike
+    # standard OTLP which uses a single base URL).
+    #
+    # To switch to a different backend, update these class constants (or
+    # have your release pipeline inject them). The code itself is
+    # backend-agnostic — it just speaks OTLP/HTTP.
+    _DEFAULT_TRACES_ENDPOINT_FALLBACK = (
+        "https://proj-xtrace-64f8c93632b0d2a93035551d6b73bcf-cn-beijing"
+        ".cn-beijing.log.aliyuncs.com/apm/trace/opentelemetry/v1/traces"
+    )
+    _DEFAULT_METRICS_ENDPOINT_FALLBACK = ""  # ARMS metrics OTLP endpoint TBD
+    _DEFAULT_LOGS_ENDPOINT_FALLBACK = ""  # ARMS logs OTLP endpoint TBD
+    _DEFAULT_HEADERS_FALLBACK = (
+        "x-arms-license-key=h9y3c809kq@6f8319efc69b73a,"
+        "x-arms-project=proj-xtrace-64f8c93632b0d2a93035551d6b73bcf-cn-beijing,"
+        "x-cms-workspace=iac-code"
+    )
+
+    def __init__(
+        self,
+        *,
+        session_id: str | None = None,
+        identity: Identity | None = None,
+        attributes: AttributeBuilder | None = None,
+        metrics: MetricsRegistry | None = None,
+        events: EventEmitter | None = None,
+        tracer: SpanFactory | None = None,
+        sink: AnalyticsSink | None = None,
+        fallback: FallbackStore | None = None,
+        settings_path: Path | None = None,
+        telemetry_dir: Path | None = None,
+    ) -> None:
+        # Default-wire every component that wasn't injected.
+        self._identity = identity or Identity(settings_path or get_settings_path(), session_id=session_id)
+        self._attributes = attributes or AttributeBuilder(self._identity, _SERVICE_NAME)
+        self._metrics = metrics or MetricsRegistry()
+        self._events = events or EventEmitter(self._attributes)
+        self._tracer = tracer or SpanFactory()
+        self._sink = sink or AnalyticsSink(self._events)
+        self._fallback = fallback or FallbackStore(telemetry_dir or (get_config_dir() / "telemetry"))
+
+        self._meter_provider: MeterProvider | None = None
+        self._logger_provider: LoggerProvider | None = None
+        self._tracer_provider: TracerProvider | None = None
+        self._bootstrapped = False
+
+    # -------- Public API --------
+
+    def log_event(self, event_name: str, metadata: dict[str, Any] | None = None) -> None:
+        self._sink.log_event(event_name, metadata or {})
+
+    def add_metric(self, name: str, value: int | float, attrs: dict[str, Any] | None = None) -> None:
+        self._metrics.add(name, value, attrs or {})
+
+    def start_span(self, name: str, attrs: dict[str, Any] | None = None):
+        return self._tracer.start(name, attrs)
+
+    def get_session_id(self) -> str:
+        return self._identity.get_session_id()
+
+    def get_user_id(self) -> str:
+        return self._identity.get_user_id()
+
+    # -------- Lifecycle --------
+
+    def bootstrap(self) -> None:
+        """Wire OTel SDK, activate sink, replay pre-queue, retry failed batches.
+
+        Idempotent.
+        """
+        if self._bootstrapped:
+            return
+        self._bootstrapped = True
+
+        resource = Resource.create(self._attributes.build_resource())
+
+        # MeterProvider
+        readers: list = []
+        if self._default_metrics_enabled():
+            readers.append(
+                PeriodicExportingMetricReader(
+                    self._build_default_metric_exporter(),
+                    export_interval_millis=_METRICS_EXPORT_INTERVAL_MS,
+                )
+            )
+        self._maybe_append_user_metric_reader(readers)
+        self._meter_provider = MeterProvider(resource=resource, metric_readers=readers)
+        self._metrics.register_all(self._meter_provider.get_meter("com.iac-code.metrics", "1.0.0"))
+
+        # LoggerProvider (Events)
+        lp = LoggerProvider(resource=resource)
+        if self._default_logs_enabled():
+            lp.add_log_record_processor(
+                BatchLogRecordProcessor(
+                    self._build_default_log_exporter(),
+                    schedule_delay_millis=_EVENTS_BATCH_DELAY_MS,
+                    max_export_batch_size=_EVENTS_BATCH_MAX_SIZE,
+                )
+            )
+        self._maybe_append_user_log_processor(lp)
+        self._logger_provider = lp
+        set_logger_provider(lp)
+        self._events.attach(lp.get_logger("com.iac-code.events", "1.0.0"))
+
+        # TracerProvider
+        tp = TracerProvider(resource=resource)
+        if self._default_traces_enabled():
+            tp.add_span_processor(BatchSpanProcessor(self._build_default_span_exporter()))
+        self._maybe_append_user_span_processor(tp)
+        self._tracer_provider = tp
+        self._tracer.attach(tp.get_tracer("com.iac-code.tracing", "1.0.0"))
+
+        # Activate sink + drain pre-queue
+        self._sink.activate()
+        self._sink.drain_soon()
+
+        # iac.init once per lifetime
+        if self._identity.was_first_run():
+            self.log_event(Events.INIT, {"is_first_run": True})
+
+        # Retry previously failed batches
+        self._retry_failed_batches()
+
+    def shutdown(self) -> None:
+        """Force-flush providers with bounded timeout; never raise."""
+        for provider, label in (
+            (self._meter_provider, "MeterProvider"),
+            (self._logger_provider, "LoggerProvider"),
+            (self._tracer_provider, "TracerProvider"),
+        ):
+            if provider is None:
+                continue
+            self._safe_flush(provider, label)
+
+    # -------- Default OTLP backend wiring helpers --------
+
+    @classmethod
+    def _traces_endpoint(cls) -> str:
+        """Full URL for traces export. Per-signal override > base + suffix > fallback."""
+        override = os.environ.get("IAC_CODE_TELEMETRY_TRACES_ENDPOINT", "").strip()
+        if override:
+            return override
+        base = os.environ.get("IAC_CODE_TELEMETRY_ENDPOINT", "").strip()
+        if base:
+            return f"{base}/v1/traces"
+        return cls._DEFAULT_TRACES_ENDPOINT_FALLBACK
+
+    @classmethod
+    def _metrics_endpoint(cls) -> str:
+        override = os.environ.get("IAC_CODE_TELEMETRY_METRICS_ENDPOINT", "").strip()
+        if override:
+            return override
+        base = os.environ.get("IAC_CODE_TELEMETRY_ENDPOINT", "").strip()
+        if base:
+            return f"{base}/v1/metrics"
+        return cls._DEFAULT_METRICS_ENDPOINT_FALLBACK
+
+    @classmethod
+    def _logs_endpoint(cls) -> str:
+        override = os.environ.get("IAC_CODE_TELEMETRY_LOGS_ENDPOINT", "").strip()
+        if override:
+            return override
+        base = os.environ.get("IAC_CODE_TELEMETRY_ENDPOINT", "").strip()
+        if base:
+            return f"{base}/v1/logs"
+        return cls._DEFAULT_LOGS_ENDPOINT_FALLBACK
+
+    @classmethod
+    def _default_headers(cls) -> dict[str, str]:
+        """Parse 'k1=v1,k2=v2' format (matches OTEL_EXPORTER_OTLP_HEADERS)."""
+        raw = os.environ.get("IAC_CODE_TELEMETRY_HEADERS", cls._DEFAULT_HEADERS_FALLBACK)
+        headers: dict[str, str] = {}
+        for part in raw.split(","):
+            part = part.strip()
+            if not part or "=" not in part:
+                continue
+            k, _, v = part.partition("=")
+            headers[k.strip()] = v.strip()
+        return headers
+
+    @classmethod
+    def _default_traces_enabled(cls) -> bool:
+        return bool(cls._traces_endpoint()) and not is_telemetry_disabled()
+
+    @classmethod
+    def _default_metrics_enabled(cls) -> bool:
+        return bool(cls._metrics_endpoint()) and not is_telemetry_disabled()
+
+    @classmethod
+    def _default_logs_enabled(cls) -> bool:
+        return bool(cls._logs_endpoint()) and not is_telemetry_disabled()
+
+    @classmethod
+    def _build_default_metric_exporter(cls) -> OTLPMetricExporter:
+        return OTLPMetricExporter(
+            endpoint=cls._metrics_endpoint(),
+            headers=cls._default_headers(),
+            timeout=5,
+        )
+
+    @classmethod
+    def _build_default_log_exporter(cls) -> OTLPLogExporter:
+        return OTLPLogExporter(
+            endpoint=cls._logs_endpoint(),
+            headers=cls._default_headers(),
+            timeout=10,
+        )
+
+    @classmethod
+    def _build_default_span_exporter(cls) -> OTLPSpanExporter:
+        return OTLPSpanExporter(
+            endpoint=cls._traces_endpoint(),
+            headers=cls._default_headers(),
+            timeout=10,
+        )
+
+    @staticmethod
+    def _user_otlp_enabled() -> bool:
+        return bool(os.environ.get("OTEL_EXPORTER_OTLP_ENDPOINT"))
+
+    def _maybe_append_user_metric_reader(self, readers: list) -> None:
+        if not self._user_otlp_enabled():
+            return
+        try:
+            readers.append(
+                PeriodicExportingMetricReader(
+                    OTLPMetricExporter(),  # reads env
+                    export_interval_millis=_METRICS_EXPORT_INTERVAL_MS,
+                )
+            )
+        except Exception as e:
+            log.warning("Failed to wire user OTLP metric exporter: %s", e)
+
+    def _maybe_append_user_log_processor(self, provider: LoggerProvider) -> None:
+        if not self._user_otlp_enabled():
+            return
+        try:
+            provider.add_log_record_processor(
+                BatchLogRecordProcessor(
+                    OTLPLogExporter(),
+                    schedule_delay_millis=_EVENTS_BATCH_DELAY_MS,
+                    max_export_batch_size=_EVENTS_BATCH_MAX_SIZE,
+                )
+            )
+        except Exception as e:
+            log.warning("Failed to wire user OTLP log exporter: %s", e)
+
+    def _maybe_append_user_span_processor(self, provider: TracerProvider) -> None:
+        if not self._user_otlp_enabled():
+            return
+        try:
+            provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter()))
+        except Exception as e:
+            log.warning("Failed to wire user OTLP span exporter: %s", e)
+
+    def _retry_failed_batches(self) -> None:
+        """Scan disk for failed batches from previous sessions, re-emit, delete."""
+        for path in self._fallback.list_pending():
+            try:
+                for event in self._fallback.read(path):
+                    name = event.pop("event.name", "iac.unknown")
+                    self._events.emit(name, event)
+                self._fallback.remove(path)
+            except Exception as e:
+                log.warning("Failed to retry batch %s: %s", path, e)
+
+    @staticmethod
+    def _safe_flush(provider: object, label: str) -> None:
+        flush = getattr(provider, "force_flush", None)
+        if flush is not None:
+            try:
+                flush(_FLUSH_TIMEOUT_MS)
+            except Exception as e:
+                log.warning("Flush %s failed: %s", label, e)
+        shutdown = getattr(provider, "shutdown", None)
+        if shutdown is not None:
+            try:
+                shutdown()
+            except Exception as e:
+                log.warning("Shutdown %s failed: %s", label, e)

iac_code/services/telemetry/config.py

@@ -0,0 +1,76 @@
+"""Privacy-level and content-capture detection for telemetry."""
+
+from __future__ import annotations
+
+import os
+from enum import Enum
+
+# =====================================================================
+# Privacy level
+# =====================================================================
+
+
+class PrivacyLevel(Enum):
+    DEFAULT = "default"
+    NO_TELEMETRY = "no-telemetry"
+    ESSENTIAL_TRAFFIC = "essential-traffic"
+
+
+_TRUTHY = {"1", "true", "yes", "on"}
+
+
+def _is_env_truthy(name: str) -> bool:
+    raw = os.environ.get(name, "").strip().lower()
+    return raw in _TRUTHY
+
+
+def get_privacy_level() -> PrivacyLevel:
+    """Most restrictive wins: ESSENTIAL_TRAFFIC > NO_TELEMETRY > DEFAULT."""
+    if _is_env_truthy("IAC_CODE_DISABLE_NONESSENTIAL_TRAFFIC"):
+        return PrivacyLevel.ESSENTIAL_TRAFFIC
+    if _is_env_truthy("DISABLE_TELEMETRY"):
+        return PrivacyLevel.NO_TELEMETRY
+    return PrivacyLevel.DEFAULT
+
+
+def is_telemetry_disabled() -> bool:
+    return get_privacy_level() != PrivacyLevel.DEFAULT
+
+
+def is_essential_traffic_only() -> bool:
+    return get_privacy_level() == PrivacyLevel.ESSENTIAL_TRAFFIC
+
+
+# =====================================================================
+# Content capture mode (gen_ai message/tool content on spans)
+# =====================================================================
+
+
+class ContentCaptureMode(Enum):
+    NO_CONTENT = "no_content"
+    SPAN_ONLY = "span_only"
+    EVENT_ONLY = "event_only"
+    SPAN_AND_EVENT = "span_and_event"
+
+
+def get_content_capture_mode() -> ContentCaptureMode:
+    """Read OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT env var.
+
+    Compatible with loongsuite-util-genai. Default: NO_CONTENT.
+    """
+    raw = os.environ.get("OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT", "").strip().upper()
+    _mapping = {
+        "SPAN_ONLY": ContentCaptureMode.SPAN_ONLY,
+        "EVENT_ONLY": ContentCaptureMode.EVENT_ONLY,
+        "SPAN_AND_EVENT": ContentCaptureMode.SPAN_AND_EVENT,
+    }
+    return _mapping.get(raw, ContentCaptureMode.NO_CONTENT)
+
+
+def should_capture_content_on_span() -> bool:
+    from iac_code.utils.log import is_debug_enabled
+
+    if is_debug_enabled():
+        return True
+    mode = get_content_capture_mode()
+    return mode in (ContentCaptureMode.SPAN_ONLY, ContentCaptureMode.SPAN_AND_EVENT)

iac_code/services/telemetry/constants.py

@@ -0,0 +1,75 @@
+"""Whitelists used by the sanitize module."""
+
+from __future__ import annotations
+
+# bundled skills keep their real name. Custom user skills
+# (outside this set) become "custom".
+BUNDLED_SKILLS: frozenset[str] = frozenset(
+    {
+        "iac_aliyun",
+    }
+)
+
+# Terraform official providers keep their real name.
+# Custom providers become "other".
+TERRAFORM_OFFICIAL_PROVIDERS: frozenset[str] = frozenset(
+    {
+        "alicloud",
+        "aws",
+        "azurerm",
+        "google",
+        "kubernetes",
+        "oci",
+        "tencentcloud",
+        "huaweicloud",
+        "volcengine",
+        "vsphere",
+        "helm",
+        "null",
+        "random",
+        "time",
+        "archive",
+        "local",
+        "external",
+        "http",
+        "tls",
+    }
+)
+
+# ROS resource type prefixes.
+ROS_ALLOWED_PREFIXES: tuple[str, ...] = ("ALIYUN::", "DATASOURCE::")
+
+# normalized model names. Unknown → "other".
+KNOWN_MODELS: frozenset[str] = frozenset(
+    {
+        # Anthropic
+        "claude-opus-4-7",
+        "claude-sonnet-4-6",
+        "claude-haiku-4-5",
+        "claude-opus-4-6",
+        "claude-sonnet-4-5",
+        "claude-haiku-4-5-20251001",
+        # OpenAI
+        "gpt-4o",
+        "gpt-4o-mini",
+        "gpt-4-turbo",
+        "o1",
+        "o1-mini",
+        "o3-mini",
+        # Dashscope / Qwen
+        "qwen-max",
+        "qwen-plus",
+        "qwen-turbo",
+        "qwen3-coder",
+        "qwen2.5-coder",
+        "qwen2.5-72b-instruct",
+    }
+)
+
+# Sentinels used throughout the module.
+CUSTOM_SKILL_PLACEHOLDER = "custom"
+OTHER_MODEL_PLACEHOLDER = "other"
+CUSTOM_TF_PROVIDER_PLACEHOLDER = "other"
+CUSTOM_ROS_RESOURCE_PLACEHOLDER = "Custom::Other"
+CUSTOM_TF_RESOURCE_PLACEHOLDER = "custom_provider::other"
+MCP_TOOL_PLACEHOLDER = "mcp_tool"

iac_code/services/telemetry/content_serializer.py

@@ -0,0 +1,124 @@
+"""Serialize messages, tools, and content for gen_ai.* span attributes.
+
+Follows the ARMS LLM trace field schema for gen_ai.input.messages,
+gen_ai.output.messages, gen_ai.system_instructions, gen_ai.tool.definitions,
+gen_ai.tool.call.arguments, and gen_ai.tool.call.result.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+_MAX_CONTENT_BYTES = 4096
+
+
+def _truncate(s: str, max_bytes: int = _MAX_CONTENT_BYTES) -> str:
+    encoded = s.encode("utf-8")
+    if len(encoded) <= max_bytes:
+        return s
+    return encoded[:max_bytes].decode("utf-8", errors="ignore") + "...[truncated]"
+
+
+def _json_dumps(obj: Any) -> str:
+    return json.dumps(obj, ensure_ascii=False, default=str)
+
+
+def serialize_user_input(user_input: str) -> str:
+    """Serialize a plain user input string to gen_ai.input.messages JSON."""
+    return _json_dumps([{"role": "user", "parts": [{"type": "text", "content": _truncate(user_input)}]}])
+
+
+def serialize_input_messages(messages: list) -> str:
+    """Serialize provider Message list to gen_ai.input.messages JSON string.
+
+    OTel semconv: [{role, parts: [{type, content|...}]}]
+    """
+    result = []
+    for msg in messages:
+        role = getattr(msg, "role", "unknown")
+        content = getattr(msg, "content", "")
+        if isinstance(content, str):
+            parts = [{"type": "text", "content": _truncate(content)}]
+        elif isinstance(content, list):
+            parts = []
+            for block in content:
+                btype = getattr(block, "type", "text")
+                if btype == "text":
+                    parts.append({"type": "text", "content": _truncate(getattr(block, "text", "") or "")})
+                elif btype == "tool_use":
+                    parts.append(
+                        {
+                            "type": "tool_call",
+                            "name": getattr(block, "name", ""),
+                            "id": getattr(block, "tool_use_id", ""),
+                        }
+                    )
+                elif btype == "tool_result":
+                    parts.append(
+                        {
+                            "type": "tool_call_response",
+                            "id": getattr(block, "tool_use_id", ""),
+                            "response": _truncate(getattr(block, "text", "") or ""),
+                        }
+                    )
+                else:
+                    parts.append({"type": btype})
+        else:
+            parts = [{"type": "text", "content": _truncate(str(content))}]
+        result.append({"role": role, "parts": parts})
+    return _json_dumps(result)
+
+
+def serialize_output_messages(text: str, finish_reason: str) -> str:
+    """Serialize assistant output to gen_ai.output.messages JSON string.
+
+    OTel semconv: [{role, parts: [{type, content}], finish_reason}]
+    """
+    return _json_dumps(
+        [
+            {
+                "role": "assistant",
+                "parts": [{"type": "text", "content": _truncate(text)}],
+                "finish_reason": finish_reason,
+            }
+        ]
+    )
+
+
+def serialize_system_instructions(system: str) -> str:
+    """Serialize system prompt to gen_ai.system_instructions JSON string."""
+    return _json_dumps([{"type": "text", "content": _truncate(system)}])
+
+
+def serialize_tool_definitions(tools: list | None) -> str:
+    """Serialize ToolDefinition list to gen_ai.tool.definitions JSON string."""
+    if not tools:
+        return "[]"
+    result = []
+    for td in tools:
+        result.append(
+            {
+                "name": getattr(td, "name", ""),
+                "type": "function",
+                "description": _truncate(getattr(td, "description", "") or ""),
+            }
+        )
+    return _json_dumps(result)
+
+
+def serialize_tool_arguments(arguments: dict | Any) -> str:
+    """Serialize tool call arguments to JSON string."""
+    if isinstance(arguments, str):
+        return _truncate(arguments)
+    return _truncate(_json_dumps(arguments))
+
+
+def serialize_tool_result(result: Any) -> str:
+    """Serialize tool call result to JSON string (truncated)."""
+    if isinstance(result, str):
+        return _truncate(result)
+    content = getattr(result, "content", None)
+    if content is not None:
+        return _truncate(str(content))
+    return _truncate(_json_dumps(result))

iac_code/services/telemetry/events.py

@@ -0,0 +1,42 @@
+"""EventEmitter — OTel Logs signal emitter."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from loguru import logger
+from opentelemetry._logs import LogRecord, SeverityNumber
+
+from iac_code.services.telemetry.attributes import AttributeBuilder
+
+
+class EventEmitter:
+    """Wraps an OTel Logger. Call `attach()` after SDK initialization."""
+
+    def __init__(self, attributes: AttributeBuilder) -> None:
+        self._attributes = attributes
+        self._otel_logger: Any = None
+
+    def attach(self, otel_logger: Any) -> None:
+        """Install the OTel Logger (or a mock during tests)."""
+        self._otel_logger = otel_logger
+
+    def emit(self, event_name: str, metadata: dict[str, Any]) -> None:
+        """Build a LogRecord and emit via the attached logger.
+
+        No-op when no logger is attached (e.g., before bootstrap or in tests
+        that don't need emission).
+        """
+        if self._otel_logger is None:
+            return
+        attrs: dict[str, Any] = {}
+        attrs.update(self._attributes.build_resource())
+        attrs.update(self._attributes.build_event(event_name))
+        attrs.update({k: v for k, v in metadata.items() if v is not None})
+        logger.debug("[event:export] {} {}", event_name, attrs)
+        record = LogRecord(
+            body=event_name,
+            severity_number=SeverityNumber.INFO,
+            attributes=attrs,
+        )
+        self._otel_logger.emit(record)