ecip-observability-stack 1.0.0

package/logging-lib/python/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ecip-observability"
+version = "1.0.0"
+description = "ECIP shared observability library — structured logging, tracing, and security event helpers for Python services"
+authors = [
+    { name = "ECIP Platform Team" }
+]
+requires-python = ">=3.11"
+dependencies = [
+    "structlog>=23.2.0",
+    "opentelemetry-api>=1.22.0",
+    "opentelemetry-sdk>=1.22.0",
+    "opentelemetry-exporter-otlp-proto-grpc>=1.22.0",
+    "opentelemetry-exporter-otlp-proto-http>=1.22.0",
+    "opentelemetry-instrumentation>=0.43b0",
+    "opentelemetry-instrumentation-grpc>=0.43b0",
+    "opentelemetry-instrumentation-requests>=0.43b0",
+    "opentelemetry-instrumentation-aiohttp-client>=0.43b0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.4.0",
+    "pytest-asyncio>=0.23.0",
+    "ruff>=0.2.0",
+    "mypy>=1.8.0",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 120
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "N", "UP", "B", "A", "C4", "SIM"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true

package/logging-lib/python/src/__init__.py

@@ -0,0 +1,19 @@
+"""
+ecip_observability — Package init
+
+Re-exports all public APIs.
+"""
+
+from .logger import get_logger, MissingObservabilityContext
+from .tracer import init_tracer, get_tracer, traced
+from .security_events import emit_auth_failure, emit_rbac_denial
+
+__all__ = [
+    "get_logger",
+    "MissingObservabilityContext",
+    "init_tracer",
+    "get_tracer",
+    "traced",
+    "emit_auth_failure",
+    "emit_rbac_denial",
+]

package/logging-lib/python/src/logger.py

@@ -0,0 +1,131 @@
+"""
+ecip_observability — Structured Logger (Python)
+
+structlog-based logger with mandatory ECIP context fields.
+Missing fields raise MissingObservabilityContext at logger creation time.
+
+Usage:
+    from ecip_observability import get_logger
+    log = get_logger(repo="acme/auth", branch="main", user_id="u_abc", module="M02")
+    log.info("Analysis complete", duration_ms=14200, files_indexed=47)
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import sys
+from datetime import datetime, timezone
+from typing import Any
+
+import structlog
+from opentelemetry import trace
+
+
+# ---------------------------------------------------------------------------
+# Exceptions
+# ---------------------------------------------------------------------------
+
+class MissingObservabilityContext(Exception):
+    """Raised when required ECIP observability fields are missing."""
+    pass
+
+
+# ---------------------------------------------------------------------------
+# Valid module identifiers
+# ---------------------------------------------------------------------------
+
+VALID_MODULES = {"M01", "M02", "M03", "M04", "M05", "M06", "M07", "M08"}
+
+
+# ---------------------------------------------------------------------------
+# structlog configuration
+# ---------------------------------------------------------------------------
+
+def _configure_structlog() -> None:
+    """Configure structlog for JSON output with ECIP mandatory fields."""
+    structlog.configure(
+        processors=[
+            structlog.contextvars.merge_contextvars,
+            structlog.processors.add_log_level,
+            structlog.processors.TimeStamper(fmt="iso", utc=True),
+            _add_trace_context,
+            structlog.processors.StackInfoRenderer(),
+            structlog.processors.format_exc_info,
+            structlog.processors.UnicodeDecoder(),
+            structlog.processors.JSONRenderer(),
+        ],
+        wrapper_class=structlog.make_filtering_bound_logger(
+            logging.getLevelName(os.environ.get("LOG_LEVEL", "INFO").upper())
+        ),
+        context_class=dict,
+        logger_factory=structlog.PrintLoggerFactory(file=sys.stdout),
+        cache_logger_on_first_use=True,
+    )
+
+
+def _add_trace_context(
+    logger: Any, method_name: str, event_dict: dict[str, Any]
+) -> dict[str, Any]:
+    """Add OpenTelemetry trace_id and span_id to every log entry."""
+    span = trace.get_current_span()
+    if span and span.is_recording():
+        ctx = span.get_span_context()
+        event_dict["trace_id"] = format(ctx.trace_id, "032x")
+        event_dict["span_id"] = format(ctx.span_id, "016x")
+    else:
+        event_dict["trace_id"] = "no-active-trace"
+        event_dict["span_id"] = "no-active-span"
+    return event_dict
+
+
+# Initialize on module import
+_configure_structlog()
+
+
+# ---------------------------------------------------------------------------
+# Logger factory
+# ---------------------------------------------------------------------------
+
+def get_logger(
+    *,
+    repo: str,
+    branch: str,
+    user_id: str,
+    module: str,
+) -> structlog.BoundLogger:
+    """
+    Create a structured ECIP logger with mandatory context fields.
+
+    All fields are required — omitting any raises MissingObservabilityContext.
+
+    Args:
+        repo: Repository in the form {org}/{repo}
+        branch: Branch being operated on
+        user_id: Hashed user identifier (no raw PII)
+        module: ECIP module identifier (M01-M08)
+
+    Returns:
+        A structlog BoundLogger with ECIP context bound
+    """
+    # Validate mandatory fields
+    if not repo:
+        raise MissingObservabilityContext("'repo' is required")
+    if not branch:
+        raise MissingObservabilityContext("'branch' is required")
+    if not user_id:
+        raise MissingObservabilityContext("'user_id' is required")
+    if not module:
+        raise MissingObservabilityContext("'module' is required")
+    if module not in VALID_MODULES:
+        raise MissingObservabilityContext(
+            f"'module' must be one of {VALID_MODULES}, got '{module}'"
+        )
+
+    return structlog.get_logger().bind(
+        repo=repo,
+        branch=branch,
+        user_id=user_id,
+        module=module,
+        env=os.environ.get("NODE_ENV", os.environ.get("ENVIRONMENT", "development")),
+    )

package/logging-lib/python/src/security_events.py

@@ -0,0 +1,150 @@
+"""
+ecip_observability — Security Event Helpers (Python)
+
+Security events route to a dedicated Elasticsearch pipeline — NEVER to
+the general log store. Use these helpers exclusively for auth/RBAC events.
+
+Usage:
+    from ecip_observability import emit_auth_failure, emit_rbac_denial
+
+    emit_auth_failure(
+        user_id="u_abc",
+        reason="jwt_expired",
+        source_ip="10.0.14.22",
+        module="M02",
+    )
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import sys
+from datetime import datetime, timezone
+from typing import Any, Literal
+
+from opentelemetry import trace
+
+
+# ---------------------------------------------------------------------------
+# Types
+# ---------------------------------------------------------------------------
+
+AuthFailureReason = Literal["jwt_expired", "jwt_invalid", "jwt_missing", "mtls_rejected"]
+RbacAction = Literal["read", "write", "admin"]
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+def _hash_user_id(user_id: str) -> str:
+    """Hash a user ID to prevent raw PII in security logs."""
+    if user_id.startswith("u_"):
+        return user_id
+    hash_hex = hashlib.sha256(user_id.encode()).hexdigest()[:12]
+    return f"u_{hash_hex}"
+
+
+def _get_trace_id() -> str:
+    """Get the current trace ID for correlation."""
+    span = trace.get_current_span()
+    if span and span.is_recording():
+        ctx = span.get_span_context()
+        return format(ctx.trace_id, "032x")
+    return "no-active-trace"
+
+
+def _emit_event(event: dict[str, Any]) -> None:
+    """
+    Emit a security event to stderr as JSON.
+    The OTel Collector's filelog receiver picks this up and routes it
+    through the security pipeline to Elasticsearch.
+    """
+    sys.stderr.write(json.dumps(event, default=str) + "\n")
+    sys.stderr.flush()
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+def emit_auth_failure(
+    *,
+    user_id: str,
+    reason: AuthFailureReason,
+    source_ip: str,
+    module: str,
+    metadata: dict[str, Any] | None = None,
+) -> None:
+    """
+    Emit an authentication failure security event.
+
+    Routes to Elasticsearch via the dedicated security event pipeline.
+    NEVER use the general logger for this.
+
+    Args:
+        user_id: User identifier (will be hashed if not already)
+        reason: Failure reason
+        source_ip: Source IP address of the request
+        module: ECIP module that detected the failure
+        metadata: Optional additional context
+    """
+    event = {
+        "@timestamp": datetime.now(timezone.utc).isoformat(),
+        "event.kind": "event",
+        "event.category": "authentication",
+        "event.type": "denied",
+        "event.outcome": "failure",
+        "trace.id": _get_trace_id(),
+        "user.id": _hash_user_id(user_id),
+        "source.ip": source_ip,
+        "reason": reason,
+        "module": module,
+    }
+    if metadata:
+        event["metadata"] = metadata
+
+    _emit_event(event)
+
+
+def emit_rbac_denial(
+    *,
+    user_id: str,
+    resource: str,
+    action: RbacAction,
+    reason: str,
+    module: str,
+    metadata: dict[str, Any] | None = None,
+) -> None:
+    """
+    Emit an RBAC denial security event.
+
+    Routes to Elasticsearch via the dedicated security event pipeline.
+    NEVER use the general logger for this.
+
+    Args:
+        user_id: User identifier (will be hashed if not already)
+        resource: Resource that was being accessed
+        action: Action attempted
+        reason: Denial reason
+        module: ECIP module that denied access
+        metadata: Optional additional context
+    """
+    event = {
+        "@timestamp": datetime.now(timezone.utc).isoformat(),
+        "event.kind": "event",
+        "event.category": "authorization",
+        "event.type": "denied",
+        "event.outcome": "failure",
+        "trace.id": _get_trace_id(),
+        "user.id": _hash_user_id(user_id),
+        "resource": resource,
+        "action": action,
+        "reason": reason,
+        "module": module,
+    }
+    if metadata:
+        event["metadata"] = metadata
+
+    _emit_event(event)

package/logging-lib/python/src/tracer.py

@@ -0,0 +1,185 @@
+"""
+ecip_observability — Distributed Tracer (Python)
+
+Initializes the OpenTelemetry Python SDK and provides a @traced decorator
+for automatic span creation.
+
+Usage:
+    from ecip_observability import init_tracer, traced
+
+    init_tracer(service_name="ecip-analysis-engine")
+
+    @traced(name="lsp.symbol_extraction")
+    def extract_symbols(file_path: str) -> list:
+        ...  # span automatically started/ended; exceptions auto-captured
+"""
+
+from __future__ import annotations
+
+import functools
+import os
+from typing import Any, Callable, TypeVar, ParamSpec
+
+from opentelemetry import trace
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor
+from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
+from opentelemetry.sdk.resources import Resource, SERVICE_NAME, SERVICE_VERSION
+from opentelemetry.trace import StatusCode, Span
+from opentelemetry.instrumentation.grpc import GrpcInstrumentorClient, GrpcInstrumentorServer
+
+
+# ---------------------------------------------------------------------------
+# Types
+# ---------------------------------------------------------------------------
+
+P = ParamSpec("P")
+T = TypeVar("T")
+
+_initialized = False
+
+
+# ---------------------------------------------------------------------------
+# SDK Initialization
+# ---------------------------------------------------------------------------
+
+def init_tracer(
+    *,
+    service_name: str,
+    service_version: str = "0.0.0",
+    otlp_endpoint: str | None = None,
+    environment: str | None = None,
+    resource_attributes: dict[str, str] | None = None,
+) -> None:
+    """
+    Initialize the OpenTelemetry Python SDK.
+
+    Must be called once at process entry, before any other imports or
+    server initialization.
+
+    Args:
+        service_name: Service name (e.g., 'ecip-analysis-engine')
+        service_version: Service version string
+        otlp_endpoint: OTLP collector endpoint (default from env)
+        environment: Deployment environment (default from env)
+        resource_attributes: Additional resource attributes
+    """
+    global _initialized
+    if _initialized:
+        import warnings
+        warnings.warn("Tracer already initialized — skipping re-initialization", stacklevel=2)
+        return
+
+    endpoint = (
+        otlp_endpoint
+        or os.environ.get("OTEL_EXPORTER_OTLP_ENDPOINT")
+        or "http://otel-collector.monitoring:4317"
+    )
+
+    env = environment or os.environ.get("ENVIRONMENT", "development")
+
+    attrs: dict[str, str] = {
+        SERVICE_NAME: service_name,
+        SERVICE_VERSION: service_version,
+        "deployment.environment": env,
+    }
+
+    # Parse OTEL_RESOURCE_ATTRIBUTES env var
+    otel_attrs = os.environ.get("OTEL_RESOURCE_ATTRIBUTES", "")
+    for pair in otel_attrs.split(","):
+        if "=" in pair:
+            key, value = pair.split("=", 1)
+            attrs[key.strip()] = value.strip()
+
+    if resource_attributes:
+        attrs.update(resource_attributes)
+
+    resource = Resource.create(attrs)
+
+    exporter = OTLPSpanExporter(endpoint=endpoint, insecure=True)
+    processor = BatchSpanProcessor(exporter)
+
+    provider = TracerProvider(resource=resource)
+    provider.add_span_processor(processor)
+
+    trace.set_tracer_provider(provider)
+
+    # Auto-instrument gRPC
+    try:
+        GrpcInstrumentorClient().instrument()
+        GrpcInstrumentorServer().instrument()
+    except Exception:
+        pass  # gRPC not in use — skip
+
+    _initialized = True
+
+
+def get_tracer(name: str = "ecip-observability") -> trace.Tracer:
+    """Get a tracer instance."""
+    return trace.get_tracer(name)
+
+
+# ---------------------------------------------------------------------------
+# @traced decorator
+# ---------------------------------------------------------------------------
+
+def traced(
+    name: str | None = None,
+    attributes: dict[str, str] | None = None,
+) -> Callable[[Callable[P, T]], Callable[P, T]]:
+    """
+    Decorator that wraps a function in an OpenTelemetry span.
+
+    Span is automatically started on function entry and ended on exit.
+    Exceptions are recorded and re-raised with span status set to ERROR.
+
+    Args:
+        name: Span name (defaults to function qualified name)
+        attributes: Additional span attributes
+
+    Usage:
+        @traced(name="lsp.symbol_extraction")
+        def extract_symbols(file_path: str) -> list:
+            ...
+    """
+    def decorator(fn: Callable[P, T]) -> Callable[P, T]:
+        span_name = name or f"{fn.__module__}.{fn.__qualname__}"
+
+        @functools.wraps(fn)
+        def sync_wrapper(*args: P.args, **kwargs: P.kwargs) -> T:
+            tracer = get_tracer()
+            with tracer.start_as_current_span(span_name) as span:
+                if attributes:
+                    for key, value in attributes.items():
+                        span.set_attribute(key, value)
+                try:
+                    result = fn(*args, **kwargs)
+                    span.set_status(StatusCode.OK)
+                    return result
+                except Exception as exc:
+                    span.set_status(StatusCode.ERROR, str(exc))
+                    span.record_exception(exc)
+                    raise
+
+        @functools.wraps(fn)
+        async def async_wrapper(*args: P.args, **kwargs: P.kwargs) -> T:
+            tracer = get_tracer()
+            with tracer.start_as_current_span(span_name) as span:
+                if attributes:
+                    for key, value in attributes.items():
+                        span.set_attribute(key, value)
+                try:
+                    result = await fn(*args, **kwargs)  # type: ignore[misc]
+                    span.set_status(StatusCode.OK)
+                    return result
+                except Exception as exc:
+                    span.set_status(StatusCode.ERROR, str(exc))
+                    span.record_exception(exc)
+                    raise
+
+        import asyncio
+        if asyncio.iscoroutinefunction(fn):
+            return async_wrapper  # type: ignore[return-value]
+        return sync_wrapper  # type: ignore[return-value]
+
+    return decorator

package/logging-lib/python/tests/test_logger.py

@@ -0,0 +1,113 @@
+"""Tests for the ECIP Python structured logger."""
+
+import json
+import pytest
+
+from unittest.mock import patch, MagicMock
+
+
+class TestGetLogger:
+    """Test the get_logger factory function."""
+
+    def test_creates_logger_with_valid_context(self):
+        from src.logger import get_logger
+
+        log = get_logger(
+            repo="acme-corp/auth-service",
+            branch="main",
+            user_id="u_8f3a1c",
+            module="M02",
+        )
+        assert log is not None
+
+    def test_raises_on_missing_repo(self):
+        from src.logger import get_logger, MissingObservabilityContext
+
+        with pytest.raises(MissingObservabilityContext, match="repo"):
+            get_logger(repo="", branch="main", user_id="u_abc", module="M02")
+
+    def test_raises_on_missing_branch(self):
+        from src.logger import get_logger, MissingObservabilityContext
+
+        with pytest.raises(MissingObservabilityContext, match="branch"):
+            get_logger(repo="acme/auth", branch="", user_id="u_abc", module="M02")
+
+    def test_raises_on_missing_user_id(self):
+        from src.logger import get_logger, MissingObservabilityContext
+
+        with pytest.raises(MissingObservabilityContext, match="user_id"):
+            get_logger(repo="acme/auth", branch="main", user_id="", module="M02")
+
+    def test_raises_on_missing_module(self):
+        from src.logger import get_logger, MissingObservabilityContext
+
+        with pytest.raises(MissingObservabilityContext, match="module"):
+            get_logger(repo="acme/auth", branch="main", user_id="u_abc", module="")
+
+    def test_raises_on_invalid_module(self):
+        from src.logger import get_logger, MissingObservabilityContext
+
+        with pytest.raises(MissingObservabilityContext, match="must be one of"):
+            get_logger(repo="acme/auth", branch="main", user_id="u_abc", module="M99")
+
+    def test_all_valid_modules(self):
+        from src.logger import get_logger, VALID_MODULES
+
+        for module in VALID_MODULES:
+            log = get_logger(
+                repo="test/repo",
+                branch="main",
+                user_id="u_test",
+                module=module,
+            )
+            assert log is not None
+
+
+class TestSecurityEvents:
+    """Test security event emission."""
+
+    def test_emit_auth_failure_format(self, capsys):
+        from src.security_events import emit_auth_failure
+
+        emit_auth_failure(
+            user_id="u_abc123",
+            reason="jwt_expired",
+            source_ip="10.0.14.22",
+            module="M01",
+        )
+
+        captured = capsys.readouterr()
+        event = json.loads(captured.err.strip())
+        assert event["event.category"] == "authentication"
+        assert event["event.type"] == "denied"
+        assert event["event.outcome"] == "failure"
+        assert event["reason"] == "jwt_expired"
+        assert event["user.id"] == "u_abc123"  # already hashed format
+
+    def test_emit_rbac_denial_format(self, capsys):
+        from src.security_events import emit_rbac_denial
+
+        emit_rbac_denial(
+            user_id="u_abc123",
+            resource="acme-corp/auth-service",
+            action="read",
+            reason="rbac_insufficient_role",
+            module="M06",
+        )
+
+        captured = capsys.readouterr()
+        event = json.loads(captured.err.strip())
+        assert event["event.category"] == "authorization"
+        assert event["resource"] == "acme-corp/auth-service"
+        assert event["action"] == "read"
+
+    def test_user_id_hashing(self):
+        from src.security_events import _hash_user_id
+
+        # Already hashed — should return as-is
+        assert _hash_user_id("u_abc123") == "u_abc123"
+
+        # Raw ID — should be hashed
+        hashed = _hash_user_id("john.doe@example.com")
+        assert hashed.startswith("u_")
+        assert len(hashed) == 15  # u_ + 12 hex chars

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "ecip-observability-stack",
+  "version": "1.0.0",
+  "private": false,
+  "description": "ECIP M08 — Observability Stack: OTel Collector, Prometheus, Tempo, Grafana, Elasticsearch",
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "lint:dashboards": "node scripts/lint-dashboards.js",
+    "lint:alerts": "promtool check rules alerts/*.yaml",
+    "validate": "npm run test && npm run lint:dashboards && npm run lint:alerts"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0",
+    "vitest": "^1.3.0",
+    "@vitest/coverage-v8": "^1.3.0",
+    "yaml": "^2.4.0",
+    "testcontainers": "^10.7.0"
+  }
+}