执行摘要

• 一句话：将 observability 相关示例文件从旧目录移动到新的 observability 目录下，重组示例结构。
• 推荐动作：该 PR 主要是目录重组，不值得深入阅读代码逻辑；但对于理解项目示例组织策略和文档更新有参考价值。

功能与动机

PR body 中说明 'Following https://github.com/vllm-project/vllm/issues/29362 Following #39979 Resettle Observability examples.'。关联 Issue #29362 提出重构示例目录结构，以使用场景（如 observability）作为一级目录，提升用户查找效率。

实现拆解

1. 移动源码文件：将 examples/offline_inference/metrics.py 重命名为 examples/observability/metrics/offline.py，将 examples/online_serving/opentelemetry/dummy_client.py 重命名为 examples/observability/opentelemetry/dummy_client.py。原因：统一 observability 相关示例，便于用户按场景查找。影响：代码功能不变，但用户需使用新路径。
2. 移动配置文件：将 Grafana、Prometheus 等仪表盘配置 JSON/YAML 文件从 examples/online_serving/dashboards/ 移动到 examples/observability/dashboards/。原因：整合观测性资源。影响：配置路径更新，确保仪表盘正常工作。
3. 更新文档：修改 docs/design/metrics.md 和 examples/observability/dashboards/README.md，更新路径引用以匹配新目录结构。原因：保持文档与代码同步。影响：用户文档更准确。

关键文件：

• examples/observability/metrics/offline.py（模块 观测性示例；类别 source；类型 rename-or-move）: 核心指标监控示例，展示如何离线获取 vLLM 指标；从 examples/offline_inference/metrics.py 移动而来。
• examples/observability/opentelemetry/dummy_client.py（模块 观测性示例；类别 source；类型 rename-or-move）: OpenTelemetry 追踪示例，演示客户端如何集成观测性；从 examples/online_serving/opentelemetry/dummy_client.py 移动而来。
• docs/design/metrics.md（模块 设计文档；类别 docs；类型 documentation）: 核心文档文件，更新了 observability 示例的路径引用，确保文档准确性。

关键符号：未识别

关键源码片段

examples/observability/metrics/offline.py

核心指标监控示例，展示如何离线获取 vLLM 指标；从 examples/offline_inference/metrics.py 移动而来。

# SPDX-License-Identifier: Apache-2.0
# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
​
from vllm import LLM, SamplingParams
from vllm.v1.metrics.reader import Counter, Gauge, Histogram, Vector
​
# 此文件已从 examples/offline_inference/metrics.py 移动到 examples/observability/metrics/offline.py
# 内容保持不变，展示离线推理时的指标监控示例。
​
# Sample prompts.
prompts = [
    "Hello, my name is",
    "The president of the United States is",
    "The capital of France is",
    "The future of AI is",
]
# Create a sampling params object.
sampling_params = SamplingParams(temperature=0.8, top_p=0.95)
​
def main():
    # Create an LLM.
    llm = LLM(model="facebook/opt-125m", disable_log_stats=False)
​
    # Generate texts from the prompts.
    outputs = llm.generate(prompts, sampling_params)
​
    # Print the outputs.
    print("-" * 50)
    for output in outputs:
        prompt = output.prompt
        generated_text = output.outputs[0].text
        print(f"Prompt: {prompt!r}\nGenerated text: {generated_text!r}")
        print("-" * 50)
​
    # Dump all metrics
    for metric in llm.get_metrics():
        if isinstance(metric, Gauge):
            print(f"{metric.name} (gauge) = {metric.value}")
        elif isinstance(metric, Counter):
            print(f"{metric.name} (counter) = {metric.value}")
        elif isinstance(metric, Vector):
            print(f"{metric.name} (vector) = {metric.values}")
        elif isinstance(metric, Histogram):
            print(f"{metric.name} (histogram)")
            print(f"    sum = {metric.sum}")
            print(f"    count = {metric.count}")
            for bucket_le, value in metric.buckets.items():
                print(f"    {bucket_le} = {value}")
​
if __name__ == "__main__":
    main()

examples/observability/opentelemetry/dummy_client.py

OpenTelemetry 追踪示例，演示客户端如何集成观测性；从 examples/online_serving/opentelemetry/dummy_client.py 移动而来。

# SPDX-License-Identifier: Apache-2.0
# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
​
import requests
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor, ConsoleSpanExporter
from opentelemetry.trace import SpanKind, set_tracer_provider
from opentelemetry.trace.propagation.tracecontext import TraceContextTextMapPropagator
​
# 此文件已从 examples/online_serving/opentelemetry/dummy_client.py 移动到 examples/observability/opentelemetry/dummy_client.py
# 内容保持不变，展示 OpenTelemetry 客户端集成示例。
​
trace_provider = TracerProvider()
set_tracer_provider(trace_provider)
​
trace_provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter()))
trace_provider.add_span_processor(BatchSpanProcessor(ConsoleSpanExporter()))
​
tracer = trace_provider.get_tracer("dummy-client")
​
url = "http://localhost:8000/v1/completions"
with tracer.start_as_current_span("client-span", kind=SpanKind.CLIENT) as span:
    prompt = "San Francisco is a"
    span.set_attribute("prompt", prompt)
    headers = {}
    TraceContextTextMapPropagator().inject(headers)
    payload = {
        "model": "facebook/opt-125m",
        "prompt": prompt,
        "max_tokens": 10,
        "n": 3,
        "use_beam_search": "true",
        "temperature": 0.0,
        # "stream": True,
    }
    response = requests.post(url, headers=headers, json=payload)

评论区精华

Review 中仅有机器的自动评论，gemini-code-assist[bot] 总结了变更内容，DarkLight1337 批准 PR，无实质性技术讨论或争议。

• 文件重组总结 (documentation): 无进一步反馈，PR 被 DarkLight1337 批准。

风险与影响

• 风险：风险较低，主要涉及路径变更：用户若直接使用旧路径运行示例可能失败；但通过文档更新可缓解。无代码逻辑变更，因此无回归、性能或安全风险。
• 影响：对用户：需要适应新的示例目录结构，可能需更新本地脚本或文档引用。对系统：无运行时影响。对团队：改善了代码库的组织性，为未来示例扩展奠定基础。
• 风险标记：路径变更影响

关联脉络

• PR #29362 [RFC]: Resettle examples.: 关联 Issue 提出重构示例目录结构的动机，本 PR 是其具体实现之一。