流处理与 RAG 驱动的 Python ETL 框架设计

• 定义与核心特征：
  • 无界数据：持续不断产生的数据流，无明确终点。
  • 低延迟：处理延迟在毫秒到秒级，追求'实时'。
  • 事件驱动：处理由单个事件或小批次事件触发。
  • 状态管理：维护处理过程中的中间状态（如窗口聚合、会话信息）。
• 关键概念：
  • 事件时间 vs 处理时间：事件发生时间 vs 系统处理时间，处理乱序事件的关键。
  • 窗口（Windowing）：将无界流划分为有限块进行聚合分析。
    • 滚动窗口：固定大小，不重叠（如每分钟统计）。
    • 滑动窗口：固定大小，可重叠（如每 30 秒统计过去 1 分钟）。
    • 会话窗口：基于活动间隙动态划分（如用户会话）。
  • 状态后端（State Backend）：存储算子状态的位置（内存、RocksDB、分布式文件系统），影响性能与容错。
  • 检查点（Checkpointing）与保存点（Savepoint）：实现容错（Exactly-Once / At-Least-Once 语义）和状态恢复。
  • 水印（Watermark）：衡量事件时间进度的机制，用于处理延迟数据并触发窗口计算。
  • 反压（Backpressure）：当下游处理速度跟不上上游时，向上游传递压力信号，防止系统崩溃。
• 主流流处理引擎对比（Python 视角）：
  • Apache Flink (PyFlink)：真正的流处理引擎，强大的状态管理和 Exactly-Once 语义，复杂事件处理（CEP）能力，高性能。PyFlink API 日益成熟。
  • Apache Spark Streaming (PySpark) / Spark Structured Streaming：统一批流 API，生态成熟，易于上手，与 Spark MLlib 无缝集成。Structured Streaming 提供更高级的抽象和优化。
  • Apache Beam (Python SDK)：统一的批流编程模型，可移植性强（支持 Flink, Spark, Google Dataflow 等 runner），强调'一次编写，到处运行'。
  • Faust (Python Native)：纯 Python 实现，轻量级，与 Kafka 深度集成，使用 asyncio，开发体验流畅，适合快速构建流处理应用。
  • Bytewax (Python Native)：受 Timely Dataflow 启发，纯 Python，强调分布式、容错、状态化流处理，API 设计简洁。
• Python 流处理库选型建议：
  • 高性能、强一致性、复杂 CEP：优先考虑 PyFlink。
  • 批流一体、生态成熟、易用性：PySpark Structured Streaming 是首选。
  • 快速原型、轻量级、Kafka 集成：Faust 或 Bytewax。
  • 跨平台可移植性：Apache Beam Python SDK。

2.2 实时分析（Real-Time Analytics）：洞察的即时获取

• 定义与目标：对流数据或近实时数据进行分析，快速生成可操作的洞察、指标或预测，支持即时决策。
• 核心能力：
  • 实时聚合：计算滑动窗口内的统计量（SUM, COUNT, AVG, MAX/MIN, DISTINCT COUNT）。
  • 复杂事件处理（CEP）：在事件流中检测特定模式（如欺诈序列、设备故障链）。
  • 实时仪表盘与可视化：将分析结果以图表、指标卡片等形式实时展示（Grafana, Superset, 自定义 Web 界面）。
  • 在线机器学习（Online ML）：模型使用新到达的数据进行增量更新或实时预测。
  • 异常检测：实时识别数据流中的异常点或模式。
• 技术栈组件：
  • 流处理引擎：作为实时分析的计算核心（见 2.1）。
  • 实时数据库/数据存储：
    • 时序数据库：专门优化时间序列数据读写（InfluxDB, TimescaleDB, Prometheus）。
    • 键值存储：低延迟读写，适合状态存储和快速查找（Redis, Aerospike）。
    • 分析型数据库：支持快速 OLAP 查询，可接收流数据写入（ClickHouse, Apache Druid, Pinot, StarRocks）。
    • 消息队列：作为分析结果的缓冲和分发点（Kafka, Pulsar）。
  • 分析框架与库：
    • Python 库：pandas (用于小批次或窗口后处理), polars (高性能 DataFrame), scikit-learn (增量学习算法), river (专门用于在线机器学习), statsmodels (统计建模)。
    • SQL 接口：许多流引擎（Flink SQL, Spark SQL, ksqlDB）和实时数据库提供 SQL 接口，降低分析门槛。
• 实时分析模式：
  • 流 -> 存储 -> 查询：流处理引擎处理数据，结果写入实时数据库（如 ClickHouse），仪表盘或 API 查询该数据库。
  • 流 -> 直接服务：流处理引擎计算结果，通过低延迟服务（如 FastAPI）直接提供给前端或下游系统。
  • 流 -> 增量模型 -> 预测服务：流数据用于更新在线 ML 模型，模型提供实时预测 API。

2.3 检索增强生成（RAG）：赋予 ETL 理解与生成能力

• RAG 的本质：一种将大型语言模型（LLM）与外部知识检索相结合的 AI 范式。LLM 负责理解、推理和生成自然语言，外部知识库（通常是向量数据库）提供事实性、时效性和领域特异性信息。
• RAG 在 ETL 中的革命性价值：
  • 非结构化数据处理：将文本、图像、音频等非结构化数据转化为结构化信息或嵌入向量，供后续分析或生成。
  • 上下文感知的转换：根据实时数据流和历史知识，动态生成转换逻辑或规则（如'将用户反馈中的负面情绪归类到具体产品模块'）。
  • 智能数据增强：利用外部知识库（如产品目录、客户档案、知识图谱）丰富实时数据（如'根据用户浏览记录，实时推荐相关产品说明书'）。
  • 自动化数据解释与报告：实时分析结果驱动 RAG 生成自然语言解释、摘要或行动建议。
  • 交互式数据探索：允许用户通过自然语言查询实时数据管道和分析结果。
• RAG 核心工作流程：
  1. 索引（Indexing - 离线/近线）：
     • 数据收集：从文档、数据库、API 等获取知识源。
     • 分块（Chunking）：将大文档切分成语义相关的片段。
     • 嵌入（Embedding）：使用嵌入模型（如 Sentence-BERT, OpenAI Embeddings）将文本块转换为向量表示。
     • 存储（Storing）：将向量及其元数据存储到向量数据库（Vector DB）。
  2. 检索与生成（Retrieval & Generation - 实时）：
     • 用户查询/上下文：接收来自实时数据流或用户的输入（如'分析当前用户反馈中关于'支付失败'的主要抱怨'）。
     • 嵌入查询：将查询/上下文转换为向量。
     • 相似性搜索：在向量数据库中查找与查询向量最相似的 Top-K 个文本块。
     • 上下文构建：将检索到的文本块与原始查询/上下文组合成提示（Prompt）。
     • LLM 生成：将构建好的提示输入 LLM，要求其基于提供的上下文生成回答或执行任务。
• Python 在 RAG 生态中的核心地位：
  • LLM 框架：LangChain, LlamaIndex 是构建 RAG 应用的事实标准，提供模块化组件（文档加载器、分块器、嵌入模型、向量存储集成、提示模板、链、代理）。
  • 嵌入模型：sentence-transformers, Hugging Face Transformers, OpenAI/Anthropic/Cohere SDKs。
  • 向量数据库客户端：几乎所有主流向量数据库（Chroma, Pinecone, Weaviate, Qdrant, Milvus, Redis, PGVector）都提供 Python SDK。
  • LLM 推理：Hugging Face Transformers (本地部署), vLLM, Text Generation Inference (高性能推理服务), OpenAI/Anthropic/Cohere SDKs (云 API)。
  • 数据处理：pandas, polars, unstructured (用于文档解析)。
• RAG 与流处理/实时分析的融合点：
  • 实时知识库更新：流处理管道将新数据（如新闻、产品更新、用户生成内容）实时处理、嵌入并更新到向量数据库。
  • 实时 RAG 查询：流处理中的事件或实时分析结果作为 RAG 的输入查询，触发检索和生成。
  • 生成结果的流式输出：LLM 生成的文本可以流式传输回数据管道或直接服务给用户。

智能 ETL 框架架构设计

3.1 设计目标与原则

• 目标：
  • 实时性：端到端延迟满足业务需求（毫秒到秒级）。
  • 可扩展性：水平扩展以应对数据量和计算负载的增长。
  • 弹性与容错：自动故障恢复，保证数据处理语义（Exactly-Once 优先）。
  • 模块化与可插拔：组件松耦合，易于替换、升级和扩展。
  • 智能化：无缝集成 RAG 能力，支持非结构化数据处理和上下文感知操作。
  • 可观测性：全面的监控、日志、指标和追踪。
  • 易用性与可维护性：清晰的 API，良好的文档，自动化部署。
• 原则：
  • 分层解耦：清晰划分数据接入、处理、存储、分析、AI、服务层。
  • 事件驱动：核心组件间通过异步消息传递解耦。
  • 状态管理显式化：明确设计状态存储位置和访问方式。
  • API 优先：关键能力通过标准化 API（REST, gRPC, WebSocket）暴露。
  • 配置驱动：行为通过外部配置管理，减少硬编码。

3.2 分层架构蓝图

+-----------------------------------------------------------------------+
| 用户接口层 (UI/API) |
| - 实时仪表盘 (Grafana, Superset, Custom Web) |
| - 查询接口 (REST API, GraphQL, WebSocket) |
| - 告警通知 (Email, Slack, PagerDuty) |
+-----------------------------------------------------------------------+
^ | (查询/订阅)
v
+-----------------------------------------------------------------------+
| 服务与编排层 (Service & Orchestration) |
| - API 网关 (Kong, Traefik, FastAPI) |
| - RAG 服务 (LangChain/LlamaIndex + FastAPI) |
| - 实时查询服务 (FastAPI + DB Client) |
| - 工作流编排 (Airflow, Dagster, Prefect - 用于管理离线索引等) |
| - 服务发现与配置 (Consul, etcd) |
+-----------------------------------------------------------------------+
^ | (请求/结果)
v
+-----------------------------------------------------------------------+
| 实时分析层 (Real-Time Analytics) |
| - 流处理引擎 (PyFlink, PySpark, Faust, Bytewax) |
| - 实时分析库 (River, scikit-learn incremental, Polars) |
| - CEP 引擎 (Flink CEP, Spark Complex Event Processing) |
| - 状态后端 (RocksDB, Redis, Distributed FS) |
+-----------------------------------------------------------------------+
^ | (处理结果/状态查询)
v
+-----------------------------------------------------------------------+
| 存储层 (Storage) |
| - 消息队列 (Kafka, Pulsar, RabbitMQ) |
| - 向量数据库 (Chroma, Pinecone, Weaviate, Qdrant, Milvus, Redis) |
| - 实时数据库 (ClickHouse, Druid, Pinot, TimescaleDB, Redis) |
| - 对象存储 (S3, GCS, MinIO) - 用于检查点、日志、模型 |
| - 关系型/NoSQL DB (PostgreSQL, MongoDB) - 元数据、配置 |
+-----------------------------------------------------------------------+
^ | (原始数据/知识源)
v
+-----------------------------------------------------------------------+
| 数据源层 (Data Sources) |
| - 流数据源 (IoT Sensors, Web Logs, Clickstreams, Market Data Feeds) |
| - 数据库 CDC (Debezium, Maxwell) |
| - 消息队列 (Kafka, Pulsar) |
| - API/Webhooks |
| - 文件系统 (实时监控新文件) |
| - 知识库 (Documents, Wikis, Databases - 用于 RAG 索引) |
+-----------------------------------------------------------------------+

3.3 核心模块详解

3.3.1 数据接入与缓冲层

• 功能：可靠、高效地捕获来自各种源头的数据，进行初步的缓冲、协议转换和格式统一。
• 关键组件：
  • 连接器（Connectors）：
    • 原生 SDK：针对特定源（如 AWS Kinesis, Azure Event Hubs）。
    • CDC 工具：Debezium, Maxwell's Demon (捕获数据库变更)。
    • 通用协议：HTTP/Webhook 接收器 (FastAPI, Flask), TCP/UDP 服务。
    • 文件监控：Watchdog (Python 库) 监控目录变化。
  • 消息队列/事件平台：
    • Apache Kafka：事实标准，高吞吐、持久化、分区、容错。Python 库：confluent-kafka, kafka-python。
    • Apache Pulsar：支持多租户、分层存储、地理复制。Python 库：pulsar-client。
    • RabbitMQ：成熟稳定，灵活的路由。Python 库：pika。
  • 数据格式：JSON, Avro, Protobuf (推荐，高效且支持 Schema 演进)。
• Python 实现要点：
  • 使用异步 IO (asyncio) 处理高并发连接。
  • 实现批处理和压缩以优化网络传输。
  • 集成 Schema Registry (如 Confluent Schema Registry) 管理 Avro/Protobuf Schema。
  • 监控接入延迟、积压量、错误率。

3.3.2 流处理引擎层

• 功能：框架的计算核心，负责对数据流进行实时的转换、过滤、聚合、连接、窗口计算、状态管理，并触发 CEP 或 RAG 操作。
• 选型与集成：
  • 根据第二章分析选择引擎（PyFlink, PySpark, Faust, Bytewax）。
  • Python API 集成：利用引擎提供的 Python SDK 编写处理逻辑。
  • UDF 支持：用 Python 编写用户自定义函数（标量、表、聚合函数）。
• 状态管理：配置状态后端（如 RocksDB），定义 TTL（Time-To-Live）防止状态无限增长。

核心处理逻辑示例（PySpark Structured Streaming）：

from pyspark.sql import SparkSession
from pyspark.sql.functions import col, from_json, window, countDistinct
from pyspark.sql.types import StructType, StructField, StringType, TimestampType

spark = SparkSession.builder.appName("RealtimeUserActivity").getOrCreate()

# 定义 Schema (假设数据是 JSON 格式)
schema = StructType([
    StructField("user_id", StringType(), True),
    StructField("event_type", StringType(), True),
    StructField("page_url", StringType(), True),
    StructField("timestamp", TimestampType(), True)
])

# 从 Kafka 读取流
kafka_df = spark.readStream \
    .format("kafka") \
    .option("kafka.bootstrap.servers","broker1:9092,broker2:9092") \
    .option("subscribe","user_activity") \
    .option("startingOffsets","latest") \
    .load()

# 解析 JSON 值
parsed_df = kafka_df.selectExpr("CAST(value AS STRING)") \
    .select(from_json("value", schema).alias("data")) \
    .select("data.*")

# 示例 1: 计算每分钟不同用户访问次数
minute_activity_df = parsed_df \
    .withWatermark("timestamp","5 minutes") \
    .groupBy(window(col("timestamp"),"1 minute"), col("event_type")) \
    .agg(countDistinct("user_id").alias("unique_users"))

# 示例 2: 检测特定事件模式 (CEP - 简化版，实际用 Flink CEP 更强大)
# 假设要检测用户连续三次登录失败
from pyspark.sql.functions import lag, count
from pyspark.sql.window import Window
login_failures_df = parsed_df.filter(col("event_type")=="login_failed")
window_spec = Window.partitionBy("user_id").orderBy("timestamp")
flagged_df = login_failures_df \
    .withColumn("prev_event_type", lag("event_type",1).over(window_spec)) \
    .withColumn("prev_prev_event_type", lag("event_type",2).over(window_spec)) \
    .filter((col("prev_event_type")=="login_failed")&(col("prev_prev_event_type")=="login_failed")) \
    .select("user_id","timestamp").distinct()

# 写入结果到控制台（或 Kafka/数据库）
query1 = minute_activity_df.writeStream \
    .outputMode("complete") \
    .format("console") \
    .start()
query2 = flagged_df.writeStream \
    .outputMode("update") \
    .format("console") \
    .start()

spark.streams.awaitAnyTermination()

3.3.3 实时分析层

• 功能：基于流处理引擎的计算结果或直接查询实时存储，执行更复杂的分析逻辑（如在线 ML、复杂聚合、异常检测）。
• 关键组件：
  • 在线机器学习服务：
    • 库：river (增量学习), scikit-learn (部分增量算法如 SGDClassifier, MiniBatchKMeans), xgboost (支持增量训练)。
    • 模式：流处理引擎将数据窗口或特征向量发送给在线模型服务，模型返回预测或更新自身。
  • 复杂事件处理（CEP）引擎：通常集成在流处理引擎中（Flink CEP），用于检测复杂模式。
  • 实时分析查询引擎：直接查询 ClickHouse/Druid 等数据库执行 Ad-hoc 分析。
• 与流处理集成：流处理作业将预处理后的特征数据发送到在线模型服务（如通过 HTTP 或 gRPC），模型服务返回预测结果，结果可写回 Kafka 或实时数据库。

Python 实现要点（River 在线学习示例）：

from river import compose, linear_model, metrics, optim, preprocessing
from river import stream

# 模拟一个实时数据流 (实际从 Kafka 等获取)
def data_stream():
    # ... 生成或获取实时特征 (X) 和标签 (y)
    # 例如：yield ({'feature1': 0.5, 'feature2': 1.2}, True)
    pass

# 定义在线模型 (线性回归 + 标准化)
model = compose.Pipeline(
    preprocessing.StandardScaler(),
    linear_model.LinearRegression(optimizer=optim.SGD(0.01))
)

# 评估指标
metric = metrics.MAE()

# 在线训练与预测
for x, y in data_stream():
    # 预测
    y_pred = model.predict_one(x)
    # 更新指标
    metric.update(y, y_pred)
    # 增量训练
    model.learn_one(x, y)
    # 输出当前性能 (可发送到监控或日志)
    print(f"MAE: {metric.get():.4f}")

3.3.4 向量存储与 RAG 引擎层

• 功能：管理知识库的嵌入向量，提供高效的相似性搜索；集成 LLM，实现检索增强生成。
• 关键组件：
  • 向量数据库：
    • 选择：根据需求（规模、性能、功能、成本）选择（Chroma 轻量易用，Pinecone/Weaviate/Qdrant 高性能云托管，Milvus 开源强大，Redis 多模态）。
    • Python SDK：所有主流 DB 都提供。
  • 嵌入模型：
    • 本地：sentence-transformers (e.g., all-MiniLM-L6-v2), Hugging Face Transformers。
    • API：OpenAI Embeddings, Cohere Embeddings。
  • LLM 框架：LangChain, LlamaIndex。
  • LLM 推理：
    • 本地：Hugging Face Transformers (CPU/GPU), vLLM, Text Generation Inference (高性能推理服务器)。
    • API：OpenAI API, Anthropic Claude API, Cohere API。
• 实时更新：流处理作业将新知识源（如新文档、产品更新）处理、嵌入后，通过向量 DB 的 Python SDK 实时更新索引。

Python 实现要点（LlamaIndex RAG 链示例）：

from llama_index.core import VectorStoreIndex, SimpleDirectoryReader
from llama_index.core.node_parser import SentenceSplitter
from llama_index.core.storage.storage_context import StorageContext
from llama_index.vector_stores.chroma import ChromaVectorStore
import chromadb

# 1. 离线/近线索引 (通常由单独工作流管理)
def build_knowledge_index(doc_path:str, collection_name:str):
    # 加载文档
    documents = SimpleDirectoryReader(doc_path).load_data()
    # 创建 Chroma 客户端和集合
    chroma_client = chromadb.Client()
    chroma_collection = chroma_client.get_or_create_collection(collection_name)
    # 设置向量存储
    vector_store = ChromaVectorStore(chroma_collection=chroma_collection)
    storage_context = StorageContext.from_defaults(vector_store=vector_store)
    # 创建索引 (自动处理分块、嵌入、存储)
    index = VectorStoreIndex.from_documents(
        documents, storage_context=storage_context,
        transformations=[SentenceSplitter(chunk_size=500, chunk_overlap=50)]
    )
    return index

# 2. 实时 RAG 查询服务 (FastAPI 集成)
from fastapi import FastAPI
from llama_index.core.query_engine import RetrieverQueryEngine
from llama_index.core.retrievers import VectorIndexRetriever

app = FastAPI()

# 假设索引已构建并持久化
# index = ... (加载或重建索引)

@app.post("/rag_query")
async def rag_query(query:str):
    # 创建检索器
    retriever = VectorIndexRetriever(index=index, similarity_top_k=3)
    # 创建查询引擎
    query_engine = RetrieverQueryEngine.from_args(retriever)
    # 执行查询
    response = query_engine.query(query)
    return{"query": query,"response":str(response)}

# 3. 流处理触发 RAG (伪代码 - 在流处理作业中)
# def process_event(event):
#     if event['type'] == 'complex_customer_query':
#         # 调用 RAG 服务 (同步或异步)
#         rag_response = requests.post("http://rag-service/rag_query", json={"query": event['query_text']}).json()
#         # 将 RAG 结果与原始事件合并，发送到下游
#         enriched_event = {**event, "rag_answer": rag_response['response']}
#         producer.send("enriched_events", value=enriched_event)

3.3.5 服务与输出层

• 功能：将处理和分析结果（包括 RAG 生成的内容）通过标准接口暴露给用户或下游系统。
• 关键组件：
  • API 服务：
    • 框架：FastAPI (高性能，自动文档), Flask (轻量灵活)。
    • 协议：REST (JSON), GraphQL (灵活查询), WebSocket (实时推送), gRPC (高性能 RPC)。
  • 实时仪表盘：
    • 工具：Grafana (连接实时数据库如 Prometheus, InfluxDB, ClickHouse), Apache Superset (BI 工具，支持实时连接), 自定义 Web 界面 (Plotly Dash, Streamlit)。
  • 告警系统：
    • 集成：流处理引擎或 API 服务检测到异常/阈值，通过 Prometheus Alertmanager, PagerDuty API, Slack Webhook 等发送通知。
  • 结果写入：将最终结果写入数据仓库（Snowflake, BigQuery）、业务数据库或消息队列供其他系统消费。

Python 实现要点（FastAPI 实时查询服务）：

from fastapi import FastAPI, HTTPException
from fastapi.responses import StreamingResponse
import asyncio
import json

app = FastAPI()

# 模拟一个实时数据库连接 (实际使用 ClickHouse/Redis 等客户端)
class RealtimeDB:
    async def query_latest_metrics(self, metric_name:str):
        # 模拟异步查询
        await asyncio.sleep(0.1)
        if metric_name =="active_users":
            return{"value":1234,"timestamp":"2023-10-27T10:30:00Z"}
        else:
            return None

db = RealtimeDB()

@app.get("/metrics/{metric_name}")
async def get_metric(metric_name:str):
    result = await db.query_latest_metrics(metric_name)
    if result is None:
        raise HTTPException(status_code=404, detail="Metric not found")
    return result

# 模拟流式输出 (例如 RAG 生成过程)
async def generate_stream_response(query:str):
    # 模拟 LLM 流式生成
    words =["This"," is"," a"," streamed"," response"," for:",f" '{query}'."]
    for word in words:
        yield f"data: {json.dumps({'token': word})}\n\n"
        await asyncio.sleep(0.2)
    # 模拟生成延迟
    yield"data: [DONE]\n\n"

@app.get("/stream_query")
async def stream_query(query:str):
    return StreamingResponse(generate_stream_response(query), media_type="text/event-stream")

3.3.6 监控与可观测性层

• 功能：全面监控框架的运行状态、性能指标、错误日志和请求追踪，确保系统健康、快速定位问题。
• 关键组件：
  • 指标（Metrics）：
    • 库：Prometheus Client (Python), OpenTelemetry Metrics。
    • 指标类型：Counter (计数器), Gauge (瞬时值), Histogram (分布), Summary (摘要)。
    • 关键指标：消息积压、处理延迟（端到端、各阶段）、吞吐量（事件/秒）、错误率、资源使用（CPU, 内存，网络）、RAG 相关（检索延迟、LLM 生成延迟、Token 使用量）。
  • 日志（Logging）：
    • 库：logging (标准库), structlog (结构化日志)。
    • 最佳实践：结构化日志（JSON 格式），包含 Trace ID、请求 ID、关键上下文。集中收集（ELK Stack - Elasticsearch, Logstash, Kibana；Loki - Grafana Loki）。
  • 追踪（Tracing）：
    • 标准：OpenTelemetry (OTel)。
    • 库：opentelemetry-api, opentelemetry-sdk, opentelemetry-instrumentation-* (自动/手动埋点)。
    • 后端：Jaeger, Zipkin, Grafana Tempo。
    • 价值：可视化请求在分布式系统中的完整调用链，定位瓶颈和错误根因。
  • 可视化与告警：
    • 工具：Grafana (统一展示 Metrics, Logs, Traces), Prometheus Alertmanager。

Python 实现要点（OpenTelemetry 集成示例）：

from opentelemetry import trace, metrics
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor, ConsoleSpanExporter
from opentelemetry.sdk.metrics import MeterProvider
from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader, ConsoleMetricExporter
from opentelemetry.exporter.jaeger.thrift import JaegerExporter
from opentelemetry.exporter.prometheus import PrometheusMetricReader
from prometheus_client import start_http_server
import time

# 1. 初始化 Tracing
trace.set_tracer_provider(TracerProvider())
tracer = trace.get_tracer(__name__)

# 导出器配置 (示例：Jaeger + Console)
jaeger_exporter = JaegerExporter(
    agent_host_name="jaeger",
    agent_port=6831,
)
span_processor = BatchSpanProcessor(jaeger_exporter)
trace.get_tracer_provider().add_span_processor(span_processor)
trace.get_tracer_provider().add_span_processor(BatchSpanProcessor(ConsoleSpanExporter()))

# 2. 初始化 Metrics
start_http_server(port=8000, addr="0.0.0.0")
reader = PrometheusMetricReader()
provider = MeterProvider(metric_readers=[reader])
metrics.set_meter_provider(provider)
meter = metrics.get_meter(__name__)

# 创建指标
event_counter = meter.create_counter("events_processed", description="Number of events processed")
processing_histogram = meter.create_histogram("event_processing_duration_ms", description="Event processing duration")

# 3. 在业务代码中使用
@tracer.start_as_current_span("process_event")
def process_event(event):
    # 记录指标
    event_counter.add(1,{"event_type": event.get("type")})
    start_time = time.time()
    try:
        # ... 实际处理逻辑 ...
        result ="processed"
    except Exception as e:
        # 记录异常到 span
        span = trace.get_current_span()
        span.record_exception(e)
        span.set_status(trace.Status(trace.StatusCode.ERROR,str(e)))
        raise
    finally:
        duration_ms =(time.time()- start_time)*1000
        processing_histogram.record(duration_ms,{"event_type": event.get("type")})
    return result