[RFC] OpenViking OpenTelemetry Unified Management Design/OpenViking OpenTelemetry 统一管理设计

[baojun-zhang]

OpenViking OpenTelemetry Unified Management Design

This RFC is bilingual (English + Chinese). English version first, Chinese version below.
本 RFC 为双语版本（英文 + 中文）。英文版在前，中文版在后。

---

English Version / 英文版

🔍 Review Items

#	Review Item	Section	Decision Needed
1	Unified context specification for root span / operation span	§4.3.2	Confirm whether the current root span / operation span attribute definitions are complete, or if any required fields are still missing.
2	Coupling introduced by Metrics ↔ Telemetry bridge	§4.5.2	Confirm whether to keep the current bridge-based coupling and adopt Scheme A as the recommended path.
3	Logs as the default observability entry point	§4.6.3	Confirm whether logs should be the default developer-facing observability entry point, with trace linkage handled underneath.
4	Recommended configuration convergence direction	§4.7.2	Confirm whether observability config should converge to server.observability.{metrics,traces,logs}.

---

1. Background and Goals

This document analyzes the current observability design in OpenViking, excluding bot, and discusses how to integrate the OpenTelemetry SDK without overturning the existing architecture, so that the three signal types of metric, trace, and log can be unified.

2. Current-State Analysis

2.1 Existing observability entry points

Entry / Capability	Output Type	Collection Method	Invocation Method	Relationship with OTel
/api/v1/observer/* /health /api/v1/debug/health	State views (non-timeseries)	Server-side instant query and aggregated state	API calls	Can be correlated with OTel trace/log for troubleshooting
/api/v1/stats/*	Analytical statistics (re-query)	Server-side re-query / scan / aggregation	API calls	Can serve as debugging / offline analysis output
/metrics	Timeseries metrics (Prometheus)	Collection side: DataSource -> Collector -> MetricRegistry Export side: PrometheusExporter	Prometheus scrape	Add OTelMetricExporter as an additional export path
OperationTelemetry (response summary + summary events)	Request-level summary (debug / diagnostics)	Collected during run_operation(), summarized at finish()	Optional API response + summary-event bridge	Works as the bridge layer across trace/metric/log: span attrs/events + metrics bridge + summary log
openviking.telemetry.tracer (OTel Trace)	Trace + log trace_id correlation	OTel TracerProvider + OTLPSpanExporter (enabled by config)	Local decorator/helper integration	The OTel Trace SDK and OTLPSpanExporter already exist; the missing piece in the original analysis context is a unified HTTP tracing middleware on the root-span main path

2.2 Existing architecture

2.2.1 Metrics

flowchart TB
    A1["HTTP Request"] --> A2["HTTP Metrics Middleware"]
    A2 --> A3["HttpRequestLifecycleDataSource"]
    A3 --> A4["HTTPCollector"]
    A4 --> A5["MetricRegistry"]

    B1["Business Events / State"] --> B2["Event / State DataSources"]
    B2 --> B3["Embedding / Retrieval / VLM / Session / Resource Collectors"]
    B3 --> A5

    C1["OperationTelemetry.finish()"] --> C2["telemetry.summary"]
    C2 --> C3["TelemetryBridgeEventDataSource"]
    C3 --> C4["TelemetryBridgeCollector"]
    C4 --> A5

    D1["Observer / Probe State"] --> D2["Observer State / Probe DataSources"]
    D2 --> D3["State / Probe Collectors"]
    D3 --> A5

    A5 --> E1["PrometheusExporter"]
    E1 --> E2["/metrics"]

Loading

• The current metrics main path is already relatively complete. Entry points include HTTP metrics middleware, business-event DataSource, state/probe DataSource, and the telemetry.summary bridge event.
• All metrics eventually converge into MetricRegistry, then PrometheusExporter renders them to /metrics.
• The core of the current metrics system is the layered openviking.metrics.* design, not tracer.py.
• A clear DataSource -> Collector -> MetricRegistry -> Exporter layering has already been formed.
• Most business code does not directly depend on Prometheus text format, so future evolution is well suited to extend from the exporter layer.
• OperationTelemetry already enters the metrics pipeline through TelemetryBridgeCollector, which gives it strong bridge value.

2.2.2 Trace

flowchart TB
    A1["HTTP Request Handling (Runtime)"] --> A2["Localized Instrumentation\n@tracer(...) / start_as_current_span()"]
    A2 --> A3["Tracer (OTel API)"]
    A3 --> A6["OTLPSpanExporter"]
    A6 --> A7["OTLP Trace Backend\n(Jaeger / Collector / APM)"]

    B1["AsyncioInstrumentor"] --> A3

Loading

• openviking.telemetry.tracer already introduces the OTel Trace SDK and can initialize TracerProvider, OTLPSpanExporter, and BatchSpanProcessor.
• On the code side, tracing is primarily integrated locally through helpers such as @tracer(...), start_as_current_span(), set(), and info().
• Basic context propagation already exists, and AsyncioInstrumentor is also supported.

2.2.3 Current log architecture

flowchart TB
    A1["Business Code logger.info/debug/error"]
    A2["logging.Logger / get_logger()"]
    A3["loguru logger"]
    A1 --> A2
    A1 --> A3

    B1["tracer._setup_logging()"]
    B2["TraceIdLoggingFilter"]
    A2 --> B2
    B1 --> B2
    B1 --> B3["loguru patcher(trace_id)"]

    A3 --> B3

    B2 --> C1["stdout / stderr / file handlers"]
    B3 --> C2["loguru output"]

Loading

• The current logging main path is a combination of logging and loguru.
• The main enhancement from tracer.py on the logging side is trace_id injection, which lets logs correlate with the current trace.

2.2.4 Operation Telemetry

OperationTelemetry has strong bridge value and already settles the core summary of a request into structured fields such as:

• duration_ms
• tokens.total
• tokens.llm.*
• tokens.embedding.*
• vector.searches/scanned/returned
• memory.extracted
• resource.process.*
• errors.stage/error_code/message

These fields have two layers of value:

• Externally, they can still be returned as part of the API response.
• Internally, they can be mapped to Span Attributes, Metrics, and Logs.

This means OpenViking already has a ready-made domain-summary model.

2.3 Problem analysis

2.3.1 Current state

OpenViking currently has four parallel but not yet fully unified observability paths:

1. Observer path: instant component-state queries for human troubleshooting.
2. Stats path: re-query interfaces for business analysis and diagnostic statistics.
3. Metrics path: a low-cardinality metric system for Prometheus scraping.
4. Telemetry/Tracing path: structured summaries and localized OTel Trace capability for a single request.

2.3.2 Problems

These paths are still individually usable but collectively fragmented:

• Metrics, logs, and tracing do not share a unified context model.
• OTel Trace already exists, but has not yet become part of the server-side main request path.
• The mapping between operation telemetry and trace/log/metric has not yet been systematized.
• There is still no unified OTel Collector / OTLP output path.

Therefore, the current goal is to evolve the existing system into a unified OTel-friendly observability architecture.

2.3.3 Trace, Metric, and Log do not share one unified context

Dimension	Metrics	Trace	Log
Path	MetricRegistry -> PrometheusExporter -> /metrics	tracer.py localized decorator/helper	logging + loguru (primarily trace_id injection)
Context	operation/status/method/route (depends on metric definition) account_id (restricted by allowlist / dimension policy)	trace_id (locally available) span_id (locally available)	trace_id (already injectable)
Gaps	No unified context model shared with trace/log	Missing a unified root span; missing an HTTP entry path; missing a unified structured field standard: request_id account_id user_id agent_id operation telemetry_id	Missing a unified structured field standard: request_id account_id user_id agent_id operation telemetry_id missing an OTLP logs pipeline

Therefore, the core goals are:

• Trace and Log need a unified context to support horizontal correlation.
• Metrics should close the observability loop through the same operation dimension plus trace/log correlation.

2.3.4 Coverage gaps of operation in openviking_operation_tokens_total

The operation dimension in openviking_operation_tokens_total currently comes from telemetry.summary.operation, and telemetry.summary is only produced on HTTP routes that explicitly integrate run_operation(). Therefore, the operations that can stably enter the openviking_operation_* metric family are fundamentally limited by which routers have already integrated operation telemetry.

Current state

• The operations that can be stably observed in openviking_operation_tokens_total are mainly:
  • search.find
  • search.search
  • resources.add_resource
• This indicates that the retrieval path and the primary resource-ingestion path have already integrated run_operation(), and that token usage is indeed generated inside those operations.
• But that does not mean other paths are not running. More commonly:
  • the corresponding route has not integrated run_operation(), so it does not produce telemetry.summary
  • or the route has integrated operation telemetry, but this request did not actually generate model tokens, so it does not enter openviking_operation_tokens_total

Root cause

• Router operations that have explicitly integrated run_operation(operation="...") currently include:
  • search.find
  • search.search
  • resources.temp_upload
  • resources.add_resource
  • resources.add_skill
  • content.write
• Among them:
  • resources.temp_upload usually does not generate model tokens, so even if it enters openviking_operation_requests_total, it may still not appear in openviking_operation_tokens_total
  • resources.add_skill and content.write only produce token samples when they actually trigger model calls
• Key paths with obvious coverage gaps currently include:
  • content.reindex
  • sessions.commit
  • other session/memory-related paths
• Although these paths may trigger stages such as memory_extract, resource_summarize, and embed_resource, they do not enter the operation-level metric path of telemetry.summary -> telemetry bridge -> openviking_operation_* because the router layer has not uniformly integrated run_operation().

Backlog to fill

It is recommended to prioritize router-level operation telemetry integration for the following operations:

1. content.reindex

   • This is an important entry point for rebuilding indexes and regenerating summaries.
   • When regenerate=true, it is a critical operation for observing resource_summarize, embed_resource, and possible vlm attribution.

2. sessions.commit

   • This is the most important entry point for memory_extract.
   • If it is not brought into operation telemetry, then even if the internal memory-extraction path has token usage, it still cannot naturally enter openviking_operation_tokens_total{operation="sessions.commit", ...}.

3. Other session/memory-related operations

   • For example, key entry points that trigger memory archival, deduplication, merge, or extraction.
   • Even if these paths do not all need to return telemetry payloads, they should still uniformly enter the operation span / summary bridge.

Conclusion

• The current operation gap in openviking_operation_tokens_total should not simply be attributed to missing collector instrumentation.
• More accurately, the problem lies in incomplete router-level operation telemetry coverage.
• Therefore, when introducing OTel root span / operation span later, filling in router-level run_operation() coverage should be treated as an explicit refactoring goal, rather than continuing patch-style extensions only at the metrics-bridge layer.

3. OTel Integration Goals

The goal is not simply to add an SDK, but to form a unified observability architecture:

1. metric continues to preserve its current low-cardinality, low-cost, and scrape-friendly characteristics.
2. trace becomes part of the server-side main request path.
3. log can be correlated with trace and metric through shared context fields.
4. operation telemetry continues to exist, but as a cross-signal semantic bridge.
5. Output can be sent uniformly to backends through OTel Collector.

4. Key Design

4.1 Scheme Description

The current OpenViking state is: highly modular Metrics, flexibly usable OTel Trace, request-level Telemetry, and Logs containing partial context. Based on this, the core path of this scheme is:

• Metric: add OTelMetricExporter to export data from the registry.
• Trace: add tracing middleware at the HTTP main entry.
• Log: add unified context injection and OTLP output on the logging side.
• Telemetry (debug): keep OperationTelemetry as the unified semantic bridge.

This scheme can reduce dependency on external components for flexible deployment (low dependency on OTel Collector), and can adapt well to heterogeneous environments (for example, commercial environments using Jaeger + Prometheus + Loki).

4.2 Data Flow Diagram

sequenceDiagram
    participant Client as Caller / HTTP Request
    participant Middleware as HTTP Tracing Middleware
    participant Router as FastAPI Router / run_operation()
    participant Trace as Trace (Root / Operation / Child Spans)
    participant Exec as Business Execution
    participant Telemetry as Telemetry (Operation Summary)
    participant Metrics as Metrics
    participant Logs as Logs
    participant Export as OTLP Exporters

    Client->>Middleware: Send request
    Middleware->>Trace: Create Root Span
    Middleware->>Router: Forward request
    Router->>Trace: Create Operation Span
    Router->>Telemetry: Bind Telemetry
    Router->>Exec: Execute business logic

    Exec->>Trace: Write Child Span / Event
    Exec->>Telemetry: Accumulate token / vector / memory / stage
    Exec->>Logs: Emit business logs
    Trace->>Logs: Inject trace_id / span_id / request_id / operation

    Router->>Telemetry: finish()
    Telemetry->>Trace: Backfill low-cardinality summary
    Telemetry->>Metrics: Bridge operation summary

    Trace->>Export: Export Trace
    Metrics->>Export: Export Metrics
    Logs->>Export: Export Logs

Loading

Once a single HTTP request enters OpenViking, trace / telemetry / metrics / log are processed on the runtime main path as shown above. The flow is:

1. After the caller sends an HTTP request, HTTP Tracing Middleware creates the Root Span and establishes the trace context for this request.
2. Once the request enters FastAPI Router / run_operation(), an Operation Span is created for the current business operation, and the Telemetry aggregation context for that operation is bound.
3. During business execution, business code writes child spans or events into Trace, while continuously accumulating summaries such as token, vector, memory, and stage into Telemetry.
4. When business code emits logs, the logging side automatically injects fields such as trace_id/span_id/request_id/operation from the current trace context, thereby associating the log with the request path.
5. When the current operation ends, Telemetry.finish() generates an operation summary; low-cardinality fields can be backfilled into Trace and further bridged into Metrics, forming metrics for aggregate query.
6. After the request completes, Trace, Metrics, and Logs are exported to the backend through OTLP Exporters; Telemetry itself is not an independently exported signal, but serves as a business-summary bridge layer that provides unified operation-level semantics for Trace and Metrics.

4.3 Unified Context Specification

By applying unified context constraints to metric/trace/log, the three signals can form an observability loop around dimensions such as account and operation.

4.3.1 Field Naming Conventions

• Custom fields in Trace/Log should stay consistent with the style of existing telemetry fields, such as request_id/account_id/operation/telemetry_id/tokens.total.
• HTTP-related fields should follow OTel semantic conventions, such as http.method/http.route/http.status_code/url.path.

4.3.2 Field Description

4.3.2.1 Root Span Context Fields

Group	Field	Description	Trace (Root Span)	Log (Structured Fields)	Metrics (Labels)
HTTP semantics	http.method	HTTP method	Required	Optional	Optional (HTTP metrics only)
HTTP semantics	http.route	Route template (avoid raw-path high cardinality)	Required (backfilled after route is resolved)	Optional	Optional (HTTP metrics only)
HTTP semantics	http.status_code	HTTP status code	Required (backfilled on response)	Optional	Optional (HTTP metrics only)
HTTP semantics	url.path	Raw path (for troubleshooting; mind privacy / high cardinality)	Optional	Optional	Not recommended (high-cardinality risk)
Request-level	request_id	Unique request identifier (reuse inbound value first, otherwise generate server-side)	Required	Required	Forbidden (high cardinality; not in labels)
Request-level	source_type / source_version	Request source type / version	Optional	Optional	Not recommended
Identity-level	account_id	Tenant / account identifier	Optional (backfilled after auth)	Optional	Conditionally allowed: account_id (allowlist metrics only)
Identity-level	user_id	User identifier	Optional (discussion item; backfilled after auth)	Optional	Forbidden (high cardinality; not in labels)
Identity-level	agent_id	Agent identifier	Optional (backfilled after auth)	Optional	Forbidden (high cardinality; not in labels)
Trace linkage	trace_id / span_id	Provided by OTel runtime	Required	Required	Forbidden (high cardinality; not in labels)

4.3.2.2 Operation Span Context Fields

Group	Field	Description	Trace (Operation Span)	Log (Structured Fields)	Metrics (Labels)
Business-level	operation	Business operation name (for example search.find)	Required	Required (when inside an operation)	Allowed: operation (aggregatable dimension)
Business-level	telemetry_id	Telemetry identifier for a single operation	Optional (for locating)	Optional (for locating)	Forbidden (high cardinality; not in labels)
Business-level	status	Business result (ok / error, etc.)	Optional	Optional	Optional: status (when low cardinality)
Business summary	tokens.* / vector.* / memory.*	Low-cardinality summary from OperationTelemetry	Optional (attributes/events)	Optional (summary log)	Depends on metric design (usually follows existing metric semantics)
Trace linkage	trace_id / span_id	Provided by OTel runtime	Required	Required	Forbidden (high cardinality; not in labels)

4.3.3 Injection Timing and Sources

The end-to-end observability path can take the HTTP request entry as the main insertion point:

• HTTP entry (tracing middleware):
  • generate / extract request_id
  • extract inbound traceparent / baggage
  • create the root span and write base HTTP fields
  • put the current span context into request scope / contextvars for subsequent business usage
• Auth / context parsing (after RequestContext is formed):
  • backfill account_id/user_id/agent_id/auth_mode into the current span and log context
• run_operation() (inside the OperationTelemetry lifecycle):
  • create the operation span
  • write operation/telemetry_id/status
  • map low-cardinality fields from OperationTelemetry into span attributes/events

4.3.4 Context Rules

• Trace: write full context fields and support create-span-first / backfill-identity-later; field names follow the short-key conventions in this section.
• Log: output context data in a structured form, while still requiring privacy-compliance design.
• Metrics: labels only allow low-cardinality, aggregatable tags such as operation, controlled account_id, and optional status.

4.4 Metrics Implementation Design

4.4.1 Design Notes

The OTel SDK itself supports implementing metrics through OTel Meter, but this is not used as the default metrics implementation in OpenViking for the following reasons:

• If business code directly uses OTel Meter as the default instrumentation entry, metric collection becomes scattered and harder to manage.
• OTel Meter does not itself provide a centralized governance layer like the current MetricRegistry; if business code writes directly to Meter, high-cardinality labels become even harder to govern uniformly.
• In heterogeneous environments such as Jaeger + Loki + Prometheus, extra orchestration / transformation layers such as OTel Collector are often required, making lightweight deployment and integration harder.

4.4.2 Design Approach

The metrics design is as follows:

• MetricRegistry remains the unified metric store.
• Collector remains the only layer allowed to write into the registry.
• Add OTelMetricExporter to support OTel-format export.
• When initializing metrics, assemble multiple exporters based on config.
• Keep /metrics fully compatible while allowing the same registry data to be exported to OTel.

4.4.3 Configuration

The metrics configuration adds an exporters section to enable multiple exporters, for example:

{
  "server": {
    "observability": {
      "metrics": {
        "enabled": true,
        "account_dimension": {
          "enabled": true,
          "max_active_accounts": 100,
          "metric_allowlist": [
            "openviking_*"
          ]
        },
        "exporters": {
          "prometheus": {
            "enabled": true
          },
          "otel": {
            "enabled": true,
            "protocol": "grpc",
            "tls": {
              "insecure": true
            },
            "endpoint": "otel-collector:4317",
            "service_name": "openviking-server",
            "export_interval_ms": 10000
          }
        }
      },
      "traces": {
        "enabled": true,
        "protocol": "grpc",
        "tls": {
          "insecure": true
        },
        "endpoint": "otel-collector:4317",
        "service_name": "openviking-server"
      },
      "logs": {
        "enabled": false,
        "protocol": "grpc",
        "tls": {
          "insecure": true
        },
        "endpoint": "otel-collector:4317",
        "service_name": "openviking-server"
      }
    }
  }
}

Benefits:

• Prometheus and OTel can be enabled at the same time.
• Each exporter has a clear configuration boundary.
• If exporter-specific parameters are added later, extension is easier.

4.5 Trace Implementation Design

4.5.1 Overall Approach

The trace design is as follows:

• Add HTTP tracing middleware as the unified entry for all requests; every inbound HTTP request should create a root span.
• Reuse the existing OTel initialization capabilities and decorator convenience in tracer.py, but elevate them into service-level infrastructure.
• Logic around tracer.py should be further converged so that provider/resource/exporter are initialized by one runtime path, reducing repeated logging patching and avoiding duplicated injection paths between loguru and standard logging.
• Keep the existing @tracer(...) decorator, but position it as a child-span helper rather than the root entry.
• Bind OperationTelemetry with the current span inside run_operation(); at the same time create an operation span for each logical operation, directly reusing the current operation naming.

4.5.2 Relationship with Telemetry

Telemetry is positioned as the business summary of trace. The boundary of responsibilities is:

• Span: describes call chain, hierarchy, timeline, exception stack, and cross-service propagation.
• Telemetry: describes domain-level summaries such as token, vector, memory, and resource-stage information.

At the end of a request, execute the following logic:

1. Telemetry.finish() generates the summary.
2. Write low-cardinality fields into the current operation span attributes.
3. Write stage information as span events.
4. Map error information to span status.
5. Continue bridging the summary into metrics using the current mechanism.
6. Write low-cardinality Telemetry fields into the operation span as attributes/events, using the telemetry summary model as the source of truth to avoid high cardinality and privacy leakage.

At present there is coupling between Metrics and Telemetry through bridge references. When telemetry=false, some metrics will not appear, such as openviking_operation_duration_seconds. Proposed solutions are:

• Scheme A: keep OperationTelemetry, but decouple response payload from collection
  • the telemetry parameter only controls whether the payload is returned
  • OperationTelemetry still executes finish() by default, continues bridging to metrics, and backfills low-cardinality fields into the operation span
  • this solves the issue where operation-level metric/trace data becomes missing when telemetry is not explicitly requested
• Scheme B: let Metrics gradually get rid of direct dependency on OperationTelemetry
  • move metrics suitable for atomic collection down into the metrics side for independent production
  • gradually narrow OperationTelemetry to business summaries and additional trace/log context, rather than the only source for metrics
  • this solves the architectural coupling issue where metrics are overly dependent on the summary bridge

4.6 Log Implementation Design

4.6.1 Design Notes

Logs are not simply about sending current logs to OTLP; three goals must be achieved:

1. Logs can be directly correlated with trace.
2. Logs have a unified set of structured context fields.
3. The output path must not feed back and impact the main business flow.

4.6.2 Design Approach

Based on the current usage pattern of openviking_cli.utils.logger.get_logger(), add the following internally:

• A unified logger context injector that extracts OTel context fields.
• A standardized formatter or JSON formatter.
• An optional OTel LoggingHandler.
• Keep existing stdout/stderr/file output paths, while supporting config switches for whether OTLP export is loaded.

Log context should come from a unified logger context injector, automatically injected from the current span and carrying fields such as trace_id/span_id/request_id/operation, so business code no longer needs to explicitly write strings like "trace_id={...}" just to build correlation.

4.6.3 Logs as the Default Observability Entry Point (Linked with Trace)

In real development, developers often have to write repetitive code to satisfy both trace and log observability needs by calling both tracer.xxx() and log.xxx(). To simplify development, it is recommended to use logs as the default observability entry point, and let them link with trace through context injection and optional bridge capabilities.

Core idea: developers should default to writing only log.xxx(); trace linkage is filled in automatically by the infrastructure, and only a small number of scenarios that require fine-grained control over span hierarchy, events, attributes, or status should explicitly use trace APIs.

Specific approach:

• Inject trace context on the logging side: trace_id/span_id/request_id/operation/...
• Provide a structured-field convention
• Associate logs with trace automatically, with no explicit developer-side correlation code

Effects:

• In day-to-day development, writing only logs is already trace-correlated by default, greatly reducing redundant code
• Trace still retains its full capability; only the default entry changes from write trace + log together to write log first
• Scenarios needing span events / child spans / precise status control can still add trace logic explicitly when needed

Applicable scenarios:

• Yes: the vast majority of business logs, state logs, and error logs
• No: scenarios requiring fine-grained control over span hierarchy, attributes, and status; those can still directly use the OTel API

Code example comparison:

# Common current approach: redundant code
with tracer.start_as_current_span("do_something") as span:
    span.set_attribute("key", value)
    logger.info(f"Start do_something, key={value}")

    try:
        result = do_something()
        span.add_event("Done", {"result": result})
        logger.info(f"do_something finished, result={result}")
        return result
    except Exception as e:
        span.record_exception(e)
        span.set_status(Status(StatusCode.ERROR))
        logger.error(f"do_something failed: {e}", exc_info=True)
        raise

# Scheme 1: log only
logger = get_logger(__name__)


def do_something():
    logger.info("Start do_something", extra={"key": value})

    try:
        result = do_something()
        logger.info("do_something finished", extra={"result": result})
        return result
    except Exception:
        logger.error("do_something failed", exc_info=True)
        raise

Automatic log output with trace context:

{
  "timestamp": "2026-04-17T10:00:00Z",
  "level": "INFO",
  "message": "Start do_something",
  "trace_id": "abc123...",
  "span_id": "def456...",
  "request_id": "req-789...",
  "operation": "chat_completion",
  "key": "value"
}

Files that need to change:

• openviking_cli/utils/logger.py: add a trace context filter
• Optional: add openviking/observability/log_trace_bridge.py to provide helpers such as log_and_add_event

Files that do not need to change:

• All business code; existing log code becomes effective automatically
• tracer.py; it remains lower-level infrastructure

4.7 Configuration Design Recommendations

4.7.1 Current Configuration State

The current server.config already contains:

• server.observability.metrics.enabled

At the same time, initialization in tracer.py depends on higher-level configuration entries such as:

• telemetry.tracer.enabled
• telemetry.tracer.endpoint
• telemetry.tracer.service_name
• telemetry.tracer.topic
• telemetry.tracer.ak
• telemetry.tracer.sk

This means the project currently has two parallel config entry points: a server-side metrics config and a global telemetry tracer config.

4.7.2 Recommended Configuration Convergence Direction

It is recommended to converge to a unified observability config block in the future, for example:

{
  "server": {
    "observability": {
      "metrics": {
        "enabled": true,
        "exporters": {
          "prometheus": {
            "enabled": true
          },
          "otel": {
            "enabled": true,
            "protocol": "grpc",
            "tls": {
              "insecure": true
            },
            "endpoint": "otel-collector:4317",
            "service_name": "openviking-server",
            "export_interval_ms": 10000
          }
        }
      },
      "traces": {
        "enabled": true,
        "protocol": "grpc",
        "tls": {
          "insecure": true
        },
        "endpoint": "otel-collector:4317",
        "service_name": "openviking-server"
      },
      "logs": {
        "enabled": true,
        "protocol": "grpc",
        "tls": {
          "insecure": true
        },
        "endpoint": "otel-collector:4317",
        "service_name": "openviking-server"
      }
    }
  }
}

---

中文版 / Chinese Version

待评审项

#	评审项	所在章节	需要决策的问题
1	统一上下文规范 root span / operation span 的属性定义	§4.3.2	确认当前 root span / operation span 的属性定义是否完整，是否仍有遗漏字段。
2	metric 与 Telemetry 桥接引用导致的耦合	§4.5.2	确认是否保留当前 bridge 方式带来的耦合，并以 方案 A 作为推荐路径。
3	是否建议日志作为默认观测入口	§4.6.3	确认是否将日志作为开发侧默认观测入口，由底层自动完成与 trace 的联动。
4	推荐配置收敛方向	§4.7.2	确认观测配置是否收敛到 server.observability.{metrics,traces,logs}。

---

OpenViking OpenTelemetry 统一管理设计

1. 背景与目标

本文分析 OpenViking 当前工程中除 bot 外的现有可观测性设计，并讨论在不推翻现有体系的前提下，如何接入 OpenTelemetry SDK，完成 metric、trace、log 三类观测信号的统一落地。

2. 现状分析

2.1 现有工程中的观测入口

入口/能力	输出类型	采集方式	调用方式	与 OTel 的关系
/api/v1/observer/* /health /api/v1/debug/health	状态视图（非时序）	服务端即时查询并聚合状态	API 调用	可用 OTel trace/log 关联排障
/api/v1/stats/*	分析型统计（重查询）	服务端重查询/扫描/聚合	API 调用	可作为调试/离线分析输出
/metrics	时序指标（Prometheus）	采集侧：DataSource -> Collector -> MetricRegistry 导出侧：PrometheusExporter	Prometheus scrape	新增 OTelMetricExporter 作为“多出口导出”
OperationTelemetry（响应摘要 + summary 事件）	请求级摘要（debug/诊断）	run_operation() 过程中采集，finish() 产出 summary	API 响应返回（可选） + summary 事件桥接	作为 trace/metric/log 的桥接层：span attrs/events + metrics bridge + summary log
openviking.telemetry.tracer（OTel Trace）	Trace + log trace_id 关联	OTel TracerProvider + OTLPSpanExporter（按配置启用）	decorator/helper 局部接入	已接入 OTel Trace SDK + OTLPSpanExporter；缺少统一 HTTP tracing middleware（root span 主链路）

2.2 现有架构

2.2.1 Metrics

flowchart TB
    A1["HTTP Request"] --> A2["HTTP Metrics Middleware"]
    A2 --> A3["HttpRequestLifecycleDataSource"]
    A3 --> A4["HTTPCollector"]
    A4 --> A5["MetricRegistry"]

    B1["Business Events / State"] --> B2["Event / State DataSources"]
    B2 --> B3["Embedding / Retrieval / VLM / Session / Resource Collectors"]
    B3 --> A5

    C1["OperationTelemetry.finish()"] --> C2["telemetry.summary"]
    C2 --> C3["TelemetryBridgeEventDataSource"]
    C3 --> C4["TelemetryBridgeCollector"]
    C4 --> A5

    D1["Observer / Probe State"] --> D2["Observer State / Probe DataSources"]
    D2 --> D3["State / Probe Collectors"]
    D3 --> A5

    A5 --> E1["PrometheusExporter"]
    E1 --> E2["/metrics"]

Loading

• 当前 metrics 主链路已经比较完整，入口包括 HTTP metrics middleware、业务事件 DataSource、状态/探针 DataSource 以及 telemetry.summary 桥接事件。
• 所有指标最终都汇聚到 MetricRegistry，再由 PrometheusExporter 输出到 /metrics。
• 当前 metrics 的核心是 openviking.metrics.* 这套分层，而不是 tracer.py。
• 已经形成 DataSource -> Collector -> MetricRegistry -> Exporter 的清晰分层。
• 业务代码多数不直接依赖 Prometheus 文本格式，后续适合从 exporter 层扩展。
• OperationTelemetry 已经通过 TelemetryBridgeCollector 进入指标链路，具备良好的桥接价值。

2.2.2 Trace

flowchart TB
    A1["HTTP 请求处理 (运行期)"] --> A2["局部埋点\n@tracer(...) / start_as_current_span()"]
    A2 --> A3["Tracer (OTel API)"]
    A3 --> A6["OTLPSpanExporter"]
    A6 --> A7["OTLP Trace Backend\n(Jaeger/Collector/APM)"]

    B1["AsyncioInstrumentor"] --> A3

Loading

• openviking.telemetry.tracer 已经引入 OTel Trace SDK，并可初始化 TracerProvider、OTLPSpanExporter 和 BatchSpanProcessor。
• 代码侧主要通过 @tracer(...)、start_as_current_span()、set()、info() 等 helper 局部接入 tracing。
• 已具备基本的上下文传播能力，也支持 AsyncioInstrumentor。

2.2.3 Log 现状架构图

flowchart TB
    A1["业务代码 logger.info/debug/error"]
    A2["logging.Logger / get_logger()"] 
    A3["loguru logger"]
    A1-->A2
    A1 --> A3

    B1["tracer._setup_logging()"]
    B2["TraceIdLoggingFilter"]
    A2 --> B2
    B1 --> B2
    B1 --> B3["loguru patcher(trace_id)"]


    A3 --> B3

    B2 --> C1["stdout / stderr / file handlers"]
    B3 --> C2["loguru output"]

Loading

• 当前日志主链路是 logging 和 loguru 的组合。
• tracer.py 对日志的主要增强注入了 trace_id，让日志与当前 trace 产生关联。

2.2.4 Operation Telemetry

OperationTelemetry 具备很强的“桥接价值”，而且已经把一次请求的核心摘要沉淀为结构化字段，例如：

• duration_ms
• tokens.total
• tokens.llm.*
• tokens.embedding.*
• vector.searches/scanned/returned
• memory.extracted
• resource.process.*
• errors.stage/error_code/message

这些字段具备两层价值：

• 对外仍可作为 API 响应的一部分；
• 对内可以映射到 Span Attributes、Metrics、Logs。

意味着 OpenViking 已经有了一层现成的领域摘要模型。

2.3 现状问题分析

2.3.1 现状

OpenViking 当前形成了 4 条并行但尚未完全统一的观测链路：

1. Observer 链路：面向人工排障的组件瞬时状态查询；
2. Stats 链路：面向业务分析和诊断统计的重查询接口；
3. Metrics 链路：面向 Prometheus 抓取的低基数指标体系；
4. Telemetry/Tracing 链路：面向单次请求的结构化摘要与局部 OTel Trace 能力。

2.3.2 问题

这几条链路目前仍然存在“各自可用、整体割裂”的问题：

• 指标、日志、追踪没有统一上下文；
• OTel Trace 已存在，但尚未成为服务端主链路的一部分；
• operation telemetry 与 trace/log/metric 的映射关系还没有系统化；
• 当前没有统一的 OTel Collector / OTLP 输出方案；

因此，当前的目标是将现有体系演进为 OTel-friendly 的统一可观测性架构。

2.3.3 Trace、Metric、Log 三个信号源没有统一上下文

维度	Metrics	Trace	Log
链路	MetricRegistry -> PrometheusExporter -> /metrics	tracer.py 局部 decorator/helper	logging + loguru （trace_id 注入为主）
上下文	operation/status/method/route（取决于指标定义） account_id（受 allowlist/维度策略约束）	trace_id（局部可得） span_id（局部可得）	trace_id（已可注入）
缺口	与 trace/log 没有统一上下文模型；	缺少统一 root span； 缺少 HTTP 入口链路 缺少统一结构化字段标准： request_id account_id user_id agent_id operation telemetry_id	缺少统一结构化字段标准： request_id account_id user_id agent_id operation telemetry_id 缺少 OTLP logs pipeline

因此,我们的目标核心是:

• Trace/Log 需要统一上下文，实现横向关联。
• Metrics 通过同一 operation 维度 + trace/log 关联实现观测闭环。

2.3.4 openviking_operation_tokens_total 的 operation 覆盖缺口

当前 openviking_operation_tokens_total 的 operation 维度来自 telemetry.summary.operation，而
telemetry.summary 只会在显式接入 run_operation() 的 HTTP 路由上产生。因此，当前能稳定进入
openviking_operation_* 指标族的 operation，本质上受限于“哪些 router 已经接入了 operation
telemetry”。

现状

• 当前通过脚本执行后，openviking_operation_tokens_total 中稳定看到的 operation 主要是：
  • search.find
  • search.search
  • resources.add_resource
• 这说明检索链路和资源导入主链路已经接入了 run_operation()，并且在这些 operation 内部确实产
  生了 token 使用。
• 但这并不代表其它链路“没有运行”，更常见的情况是：
  • 对应路由没有接入 run_operation()，因此不会产出 telemetry.summary
  • 或者虽然路由接入了 operation telemetry，但本次请求没有实际产生 token，因此不会进入
    openviking_operation_tokens_total

根因

• 当前已明确接入 run_operation(operation=\"...\") 的 router operation 包括：
  • search.find
  • search.search
  • resources.temp_upload
  • resources.add_resource
  • resources.add_skill
  • content.write
• 其中：
  • resources.temp_upload 通常不会产生模型 token，因此即使进入 openviking_operation_requests_total
    ，也不一定会出现在 openviking_operation_tokens_total
  • resources.add_skill / content.write 只有在实际触发模型调用时才会出现 token 样本
• 当前明显存在覆盖缺口的关键链路包括：
  • content.reindex
  • sessions.commit
  • 以及其它 session/memory 相关路径
• 这些链路虽然可能触发 memory_extract、resource_summarize、embed_resource 等 stage，但由于
  router 层没有统一接入 run_operation()，因此不会进入 telemetry.summary -> telemetry bridge -> openviking_operation_* 这一套 operation 级指标链路。

待补齐清单

建议优先补齐下列 operation 的 router 级 operation telemetry 接入：

1. content.reindex

   • 这是资源重建索引/重新生成摘要的重要入口。
   • 当 regenerate=true 时，它是观察 resource_summarize、embed_resource，以及可能出现的
     vlm 归因的重要 operation。

2. sessions.commit

   • 这是 memory_extract 最关键的入口。
   • 如果不把它纳入 operation telemetry，后续即使 memory 提取链路内部有 token，也无法自然进入
     openviking_operation_tokens_total{operation=\"sessions.commit\", ...}。

3. 其它 session/memory 相关 operation

   • 例如会触发 memory 归档、去重、合并、抽取的关键入口。
   • 这些链路即使未必都需要返回 telemetry payload，也应统一进入 operation span / summary bridge。

结论

• 当前 openviking_operation_tokens_total 的 operation 缺口，不应简单归因于“collector 漏埋点”。
• 更准确地说，问题出在 router 层 operation telemetry 覆盖范围不完整。
• 因此，后续在引入 OTel root span / operation span 时，应把“补齐 router 级 run_operation() 覆盖”
  作为一个明确的改造目标，而不是仅在 metrics bridge 层继续补丁式扩展。

3. OTel 集成目标

目标不是简单“加一个 SDK”，而是形成统一观测架构：

1. metric 继续保留当前低基数、低成本、可抓取特征；
2. trace 成为服务端请求主链路的一部分；
3. log 能够和 trace、metric 通过上下文字段关联；
4. operation telemetry 继续存在，但作为跨信号的语义桥接层；
5. 可以通过 OTel Collector 统一输出到后端。

4. 关键方案设计

4.1 方案说明

OpenViking 现状为高度模块化的 Metric、具备可灵活使用的 Otel Trace、请求维度的Telemetry、包含了部分上下文的 Log，基于上述现状，本方案核心路径如下:

• Metric :新增 OTelMetricExporter，把 registry 中的数据进行导出；
• Trace: 在 HTTP 主入口增加 tracing middleware；
• Log: 在日志侧增加统一上下文注入与 OTLP 输出能力；
• Telemetry(debug): 保留 OperationTelemetry 作为统一语义桥。

该方案可以降低对外部组件的依赖进行灵活部署(对 Otel-Collector 的依赖性低)，针对于异构环境可以有很好的适配(比如 Jaeger+Prometheus+Loki 的商业化环境)。

4.2 数据流向图

sequenceDiagram
    participant Client as 调用方 / HTTP 请求
    participant Middleware as HTTP Tracing Middleware
    participant Router as FastAPI Router / run_operation()
    participant Trace as Trace (Root / Operation / Child Spans)
    participant Exec as Business Execution
    participant Telemetry as Telemetry (Operation Summary)
    participant Metrics as Metrics
    participant Logs as Logs
    participant Export as OTLP Exporters

    Client->>Middleware: 发起请求
    Middleware->>Trace: 创建 Root Span
    Middleware->>Router: 转发请求
    Router->>Trace: 创建 Operation Span
    Router->>Telemetry: 绑定 Telemetry
    Router->>Exec: 执行业务逻辑

    Exec->>Trace: 写入 Child Span / Event
    Exec->>Telemetry: 累加 token / vector / memory / stage
    Exec->>Logs: 输出业务日志
    Trace->>Logs: 注入 trace_id / span_id / request_id / operation

    Router->>Telemetry: finish()
    Telemetry->>Trace: 回填低基数摘要
    Telemetry->>Metrics: 桥接 operation summary

    Trace->>Export: 导出 Trace
    Metrics->>Export: 导出 Metrics
    Logs->>Export: 导出 Logs

Loading

一次 HTTP 请求进入 OpenViking 后，trace / telemetry / metrics / log 在运行时主链路上如上进行处理，步骤如下:

1. 调用方发起 HTTP 请求后，HTTP Tracing Middleware 作为入口创建 Root Span，建立本次请求的 trace 上下文。
2. 请求进入 FastAPI Router / run_operation() 后，为当前业务操作创建 Operation Span，并绑定本次 operation 对应的 Telemetry 聚合上下文。
3. Business Execution 在执行业务逻辑过程中，一方面向 Trace 写入 child span 或 event，另一方面持续向 Telemetry 累加 token、vector、memory、stage 等业务摘要。
4. 业务代码输出日志时，日志侧通过当前 trace 上下文自动注入 trace_id/span_id/request_id/operation 等字段，从而与本次请求链路建立关联。
5. 当前 operation 结束时，Telemetry.finish() 生成 operation summary；其中低基数字段可回填到 Trace，并继续桥接到 Metrics，形成面向聚合查询的指标。
6. 请求完成后，Trace、Metrics、Logs 分别通过 OTLP Exporters 输出到后端；其中 Telemetry 自身不是独立导出信号，而是作为业务摘要桥接层，为 Trace 和 Metrics 提供统一的 operation 级语义。

4.3 统一上下文规范

我们可以通过对 metric/trace/log 进行统一的上下文规范约束，让三者可以在任何环境下都形成一定维度(account、 operation)观测闭环。

4.3.1 字段命名约定

• 自定义字段在 Trace/Log 中与现有 telemetry 字段风格保持一致，例如 request_id/account_id/operation/telemetry_id/tokens.total。
• HTTP 相关字段遵循 OTel 语义约定（如 http.method/http.route/http.status_code/url.path）。

4.3.2 字段说明

4.3.2.1 Root Span 上下文字段

分组	字段	说明	Trace（Root Span）	Log（结构化字段）	Metrics（Labels）
HTTP 语义	http.method	HTTP 方法	必填	可选	可选（仅 HTTP 指标使用）
HTTP 语义	http.route	路由模板（避免原始 path 高基数）	必填（获取到 route 后补写）	可选	可选（仅 HTTP 指标使用）
HTTP 语义	http.status_code	HTTP 状态码	必填（响应时补写）	可选	可选（仅 HTTP 指标使用）
HTTP 语义	url.path	原始 path（用于排障，注意隐私/高基数）	可选	可选	不建议（高基数风险）
请求级	request_id	请求唯一标识（优先复用外部传入，否则服务端生成）	必填	必填	禁止（高基数，不进入 labels）
请求级	source_type / source_version	请求来源类型/版本	选填	选填	不建议
身份级	account_id	租户/账号标识	选填（鉴权后补写）	选填	条件允许：account_id（仅 allowlist 指标）
身份级	user_id	用户标识	选填（讨论点，鉴权后补写）	选填	禁止（高基数，不进入 labels）
身份级	agent_id	agent 标识	选填（鉴权后补写）	选填	禁止（高基数，不进入 labels）
Trace 关联	trace_id / span_id	由 OTel runtime 提供	必填	必填	禁止（高基数，不进入 labels）

4.3.2.2 Operation Span 上下文字段

分组	字段	说明	Trace（Operation Span）	Log（结构化字段）	Metrics（Labels）
业务级	operation	业务操作名（如 search.find）	必填	必填（若在 operation 内）	允许：operation（可聚合维度）
业务级	telemetry_id	单次 operation 的 telemetry 标识	选填（用于定位）	选填（用于定位）	禁止（高基数，不进入 labels）
业务级	status	业务结果（ok/error 等）	选填	选填	可选：status（低基数时可用）
业务摘要	tokens.* / vector.* / memory.*	来自 OperationTelemetry 的低基数字段摘要	选填（attributes/events）	可选（summary log）	视指标设计而定（通常以 metrics 侧已有口径为准）
Trace 关联	trace_id / span_id	由 OTel runtime 提供	必填	必填	禁止（高基数，不进入 labels）

4.3.3 注入时机与来源

整体链路式可观测行可以以 HTTP 请求入口作为切入点

• HTTP 入口（tracing middleware）：
  • 生成/提取 request_id
  • 提取入站 traceparent / baggage
  • 创建 root span，并写入基础 HTTP 字段
  • 将当前 span 上下文放进 request scope/contextvars 中，供后续业务使用
• 鉴权/上下文解析（RequestContext 形成后）：
  • 补写 account_id/user_id/agent_id/auth_mode 到当前 span 与日志上下文
• run_operation()（OperationTelemetry 生命周期内）：
  • 创建 operation span
  • 写入 operation/telemetry_id/status
  • 将 OperationTelemetry 的低基数字段映射为 span attributes/events

4.3.4 上下文规则

• Trace：写入完整上下文字段（并支持“先建 span，后补写身份字段”），字段名遵循本节短 key 规范。
• Log：结构化输出上下文数据，但是需要提供隐私合规设计
• Metrics：labels 仅允许低基数、可聚合标签（如 operation、受控 account_id、可选 status）

4.4 Metrics 落地设计

4.4.1 设计说明

Otel SDK 本身支持 OTel Meter 的 Metric 实现方式， 但这里不作为 OpenViking Metric 的默认实现，其理由如下:

• 如果代码直接使用 OTel Meter 作为默认埋点入口，会导致指标收集分散，难以管理
• OTel Meter 本身不提供像当前 MetricRegistry 这样集中治理层，若直接让业务代码写 Meter，会更难统一治理高基数标签
• 在异构环境中(比如 Jaeger + Loki + Prometheus)，通常需要额外的编排/转换层(如 Otel Collector)，在这种情况下难以实现轻量化部署及接入。

4.4.2 设计思路

Metric 的设计思路如下：

• MetricRegistry 继续作为统一指标存储；
• Collector 仍然是唯一允许写 registry 的层；
• 新增OtelExporter用于支持 Otel格式导出；
• 在 metrics 初始化时，根据配置装配多个 exporter；
• 保持 /metrics 完整兼容，同时允许将同一份 registry 数据导出到 OTel。

4.4.3 配置

metrics 配置增加 exporters 配置项，用于启用多个 exporter，例如：

{
  "server": {
    "observability": {
      "metrics": {
        "enabled": true,
        "account_dimension": {
          "enabled": true,
          "max_active_accounts": 100,
          "metric_allowlist": [
            "openviking_*"
          ]
        },
        "exporters": {
          "prometheus": {
            "enabled": true
          },
          "otel": {
            "enabled": true,
            "protocol": "grpc",
            "tls": {
              "insecure": true
            },
            "endpoint": "otel-collector:4317",
            "service_name": "openviking-server",
            "export_interval_ms": 10000
          }
        }
      },
      "traces": {
        "enabled": true,
        "protocol": "grpc",
        "tls": {
          "insecure": true
        },
        "endpoint": "otel-collector:4317",
        "service_name": "openviking-server"
      },
      "logs": {
        "enabled": false,
        "protocol": "grpc",
        "tls": {
          "insecure": true
        },
        "endpoint": "otel-collector:4317",
        "service_name": "openviking-server"
      }
    }
  }
}

这样做的好处是：

• Prometheus 和 OTel 可以同时启用；
• 每个 exporter 的配置边界清晰；
• 后续若要增加 exporter 专属参数，也更容易扩展。

4.5 Trace 落地设计

4.5.1 总体思路

Trace 设计如下：

• 新增 HTTP tracing middleware，作为所有请求的统一入口，每个入站 HTTP 请求都应创建一个 root span。
• 复用当前 tracer.py 中已有的 OTel 初始化能力与 decorator 的便捷能力，但把它提升为服务级基础设施；
• tracer.py 相关逻辑应进一步收敛：统一由一处 runtime 初始化 provider/resource/exporter，减少重复 patch logging，避免 loguru 与标准 logging 在注入链路上重复工作。
• 现有 @tracer(...) decorator 保留，但定位为子 span 辅助能力，而不是根入口。
• run_operation() 内将 OperationTelemetry 与当前 span 绑定；同时为每个逻辑操作创建 operation span，名称可直接复用当前 operation 命名。

4.5.2 与 Telemetry 的关系

Telemetry 定位为 trace 的业务摘要，两者职责边界如下：

• Span：描述调用链、层次关系、时间线、异常栈和跨服务传播；
• Telemetry：描述领域级摘要，如 token、vector、memory、resource 阶段信息。

在请求结束时，执行以下逻辑：

1. Telemetry.finish() 生成摘要；
2. 将低基数字段写入当前 operation span attributes；
3. 将阶段性信息写成 span event；
4. 将错误信息映射为 span status；
5. 将摘要继续按当前逻辑桥接到 metrics。
6. Telemetry 的低基数字段以 attributes/events 方式写入 operation span，具体字段以 Telemetry 摘要模型为准（避免高基数与隐私泄露）。

目前 metric 与Telemetry存在桥接引用的情况，当telemetry=false 时，部分指标将不会出现(如openviking_operation_duration_seconds等)，解决方案如下

• 方案 A：保留 OperationTelemetry，解耦回包与采集
  • telemetry 参数只控制是否返回 payload
  • OperationTelemetry 默认仍可执行 finish() 并继续 bridge 到 metrics，同时把低基数字段回填到 operation span
  • 解决“未显式请求 telemetry 时 operation 级 metric/trace 缺数据”的问题
• 方案 B：Metrics 逐步摆脱对 OperationTelemetry 的依赖
  • 把适合原子采集的指标直接下沉到 metrics 侧独立产出
  • OperationTelemetry 逐步收敛为业务摘要和 trace/log 附加上下文，而不是 metrics 的唯一来源
  • 解决“metrics 过度依赖 summary bridge”的架构耦合问题

4.6 Log 落地设计

4.6.1 设计说明

日志不是简单地“把现在的日志发到 OTLP”，而是要达成三件事：

1. 日志与 trace 能直接关联；
2. 日志具备统一结构化上下文字段；
3. 输出链路不反向影响主业务。

4.6.2 设计思路

在当前 openviking_cli.utils.logger.get_logger() 的使用方式基础上，内部增加：

• 统一 logger context injector提取OTel 上下文字段；
• 标准化 formatter 或 JSON formatter；
• 可选的 OTel LoggingHandler；
• 保持现有 stdout/stderr/file 输出路径，并支持开关控制是否加载 OTLP 导出。

日志上下文应该来自统一 logger context injector，从当前 span 中自动注入，自动携带 trace_id/span_id/request_id/operation 等字段，这样就不需要在业务代码中显式写入"trace_id={...}"进行关联。

4.6.3 日志作为默认观测入口（与 trace 联动）

在实际开发中，为了同时满足 trace 和 log 的可观测性需求，开发人员经常需要写重复代码：同时写 tracer.xxx() 和 log.xxx()。为简化开发，推荐把日志作为默认观测入口，并通过上下文注入与可选 bridge 能力和 trace 联动。

核心思路：让开发默认只写 log.xxx()；trace 关联由底层自动补齐，只有少数需要精细控制 span 层次、事件、属性、状态的场景再显式使用 trace API。

具体做法：

• 日志侧统一注入 trace 上下文（trace_id/span_id/request_id/operation/...）
• 提供结构化字段规范
• 日志自动与 trace 关联，无需开发显式写入

效果：

• 开发日常只写日志就已经“默认可关联到 trace”，大幅减少冗余代码
• trace 仍然保留完整能力；只是默认入口从“同时写 trace + log”收敛为“先写 log”
• 需要 span event / child span / 精细 status 控制的场景再额外补充（可选）

适用场景：

• ✅ 绝大多数业务日志、状态日志、错误日志
• ❌ 需要精细控制 span 层次、属性、状态的场景（此时仍可直接使用 OTel API）

代码示例对比：

# 当前常见做法：冗余代码
with tracer.start_as_current_span("do_something") as span:
    span.set_attribute("key", value)
    logger.info(f"开始执行 do_something, key={value}")  # 重复写
    
    try:
        result = do_something()
        span.add_event("完成", {"result": result})
        logger.info(f"do_something 完成, result={result}")  # 重复写
        return result
    except Exception as e:
        span.record_exception(e)
        span.set_status(Status(StatusCode.ERROR))
        logger.error(f"do_something 失败: {e}", exc_info=True)  # 重复写
        raise

# 方案一：只写日志
logger = get_logger(__name__)


def do_something():
    logger.info("开始执行 do_something", extra={"key": value})

    try:
        result = do_something()
        logger.info("do_something 完成", extra={"result": result})
        return result
    except Exception as e:
        logger.error("do_something 失败", exc_info=True)
        raise

日志输出效果（自动携带 trace 上下文）：

{
  "timestamp": "2026-04-17T10:00:00Z",
  "level": "INFO",
  "message": "开始执行 do_something",
  "trace_id": "abc123...",
  "span_id": "def456...",
  "request_id": "req-789...",
  "operation": "chat_completion",
  "key": "value"
}

需要改动的文件：

• openviking_cli/utils/logger.py：增加 trace context filter
• （可选）新增 openviking/observability/log_trace_bridge.py：提供 log_and_add_event 等便捷函数

不需要改动的文件：

• 所有业务代码（现有日志代码自动生效）
• tracer.py（保持不变，作为底层基础设施）

4.7 配置设计建议

4.7.1 当前配置现状

当前 server.config 中已有：

• server.observability.metrics.enabled

而 tracer.py 的初始化又依赖更上层配置中的：

• telemetry.tracer.enabled
• telemetry.tracer.endpoint
• telemetry.tracer.service_name
• telemetry.tracer.topic
• telemetry.tracer.ak
• telemetry.tracer.sk

这意味着当前配置存在“server 侧 metrics 配置”和“全局 telemetry tracer 配置”双入口并存的情况。

4.7.2 推荐配置收敛方向

建议后续收敛为统一观测配置块，例如：

{
  "server": {
    "observability": {
      "metrics": {
        "enabled": true,
        "exporters": {
          "prometheus": {
            "enabled": true
          },
          "otel": {
            "enabled": true,
            "protocol": "grpc",
            "tls": {
              "insecure": true
            },
            "endpoint": "otel-collector:4317",
            "service_name": "openviking-server",
            "export_interval_ms": 10000
          }
        }
      },
      "traces": {
        "enabled": true,
        "protocol": "grpc",
        "tls": {
          "insecure": true
        },
        "endpoint": "otel-collector:4317",
        "service_name": "openviking-server"
      },
      "logs": {
        "enabled": true,
        "protocol": "grpc",
        "tls": {
          "insecure": true
        },
        "endpoint": "otel-collector:4317",
        "service_name": "openviking-server"
      }
    }
  }
}