mingx 0.1.0__py3-none-any.whl → 0.1.1__py3-none-any.whl

mingx/_trace.py

@@ -11,7 +11,7 @@ from typing import Any, Dict, Literal, Optional
 
 from opentelemetry import trace
 from opentelemetry.sdk.trace import TracerProvider
-from opentelemetry.sdk.trace.export import BatchSpanProcessor, SpanExporter
+from opentelemetry.sdk.trace.export import BatchSpanProcessor, SimpleSpanProcessor, SpanExporter
 from opentelemetry.trace import Tracer
 
 from mingx._default_attributes import DefaultAttributesSpanProcessor
@@ -50,6 +50,7 @@ def configure_tracer_provider(
     user_id: Optional[str] = None,
     extra_attributes: Optional[Dict[str, Any]] = None,
     use_baggage: bool = True,
+    use_batch_processor: bool = True,
 ) -> TracerProvider:
     """
     Create and set the global TracerProvider with BatchSpanProcessor and OTLP export.
@@ -75,6 +76,8 @@ def configure_tracer_provider(
         use_baggage: If True (default), read mingx.workspace_id, mingx.span_type,
             mingx.user.id from Baggage and overlay on span (Baggage overrides defaults).
             span_type 不在初始化时设置，由 @traced(span_type=...) 或适配器按调用类型设置。
+        use_batch_processor: If True (default), use BatchSpanProcessor，span 在 trace 结束或缓冲区满时批量上送；
+            If False, use SimpleSpanProcessor，每个 span 结束时立即上送，便于按节点完成顺序在服务端看到顺序。
 
     Returns:
         The TracerProvider that is now set as global.
@@ -101,7 +104,10 @@ def configure_tracer_provider(
             auth_scheme=auth_scheme,
         )
 
-    provider.add_span_processor(BatchSpanProcessor(exporter))
+    if use_batch_processor:
+        provider.add_span_processor(BatchSpanProcessor(exporter))
+    else:
+        provider.add_span_processor(SimpleSpanProcessor(exporter))
     trace.set_tracer_provider(provider)
     return provider
 

mingx/adapters/langchain.py

@@ -181,6 +181,7 @@ class OpenTelemetryCallbackHandler(BaseCallbackHandler):
     trace_content: bool = True  # 默认记录所有节点的入参（输入）与返回值（输出），无返回值记空
     record_input_output_as: RecordInputOutputAs = "events"  # 推荐 events，与 Traceloop 等一致
     max_content_length: Optional[int] = None  # 可选，单条 content 截断长度（字符）
+    root_span_name: Optional[str] = None  # 可选，指定根 Span 名称（仅对无 parent_run_id 的 chain 生效）
 
     def __init__(
         self,
@@ -188,11 +189,13 @@ class OpenTelemetryCallbackHandler(BaseCallbackHandler):
         trace_content: bool = True,
         record_input_output_as: RecordInputOutputAs = "events",
         max_content_length: Optional[int] = None,
+        root_span_name: Optional[str] = None,
     ) -> None:
         super().__init__()
         self.trace_content = trace_content
         self.record_input_output_as = record_input_output_as
         self.max_content_length = max_content_length
+        self.root_span_name = root_span_name
 
     def _start_span(
         self,
@@ -428,6 +431,10 @@ class OpenTelemetryCallbackHandler(BaseCallbackHandler):
             kw_name = kwargs.get("name")
             if kw_name is not None and str(kw_name).strip():
                 name = kw_name
+        # Root span 名称：无 parent_run_id 视为根 run 时，使用创建 handler 时指定的 root_span_name
+        parent_run_id = kwargs.get("parent_run_id")
+        if parent_run_id is None and self.root_span_name and str(self.root_span_name).strip():
+            name = str(self.root_span_name).strip()
         if not isinstance(name, str):
             name = str(name)
         span_attrs = ChainSpanAttributes(run_id=str(run_id))
@@ -637,10 +644,12 @@ def get_langchain_callback(
     trace_content: bool = True,
     record_input_output_as: RecordInputOutputAs = "events",
     max_content_length: Optional[int] = None,
+    root_span_name: Optional[str] = None,
 ) -> OpenTelemetryCallbackHandler:
     """Return a default OpenTelemetryCallbackHandler for LangChain/LangGraph. 默认记录所有节点入参与返回值。"""
     return OpenTelemetryCallbackHandler(
         trace_content=trace_content,
         record_input_output_as=record_input_output_as,
         max_content_length=max_content_length,
+        root_span_name=root_span_name,
     )

mingx/decorator.py

@@ -40,6 +40,12 @@ def traced(
         @traced(name="custom_span", span_type="model", attributes={"key": "value"})
         def other(): ...
 
+        # 指定 root span 名称：入口函数用 name= 即可，该 span 即为 trace 的 root
+        @traced(name="my_agent")
+        def entry():
+            ...
+
+    name: Span 名称；不传时使用「模块.函数名」或「函数名」。作为入口调用时，该 name 即为 root span name。
     span_type: 设置 mingx.span_type，如 "model", "retriever", "tool", "chain", "agent" 等（可扩展）。
     record_io: 是否记录函数入参（输入）与返回值（输出），默认 True，与适配器行为一致。
     record_io_as: "events"（默认）| "attributes" | "none"。

{mingx-0.1.0.dist-info → mingx-0.1.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mingx
-Version: 0.1.0
+Version: 0.1.1
 Summary: OpenTelemetry trace Python SDK with GenAI semantic conventions, LangChain/LangGraph callbacks, and method-level @traced decorator
 Requires-Python: >=3.10
 Requires-Dist: opentelemetry-api>=1.20.0
@@ -70,12 +70,14 @@ configure_tracer_provider(
     workspace_id="ws-001",
     user_id="user-123",
 )
+# LangChain/LangGraph 等有节点先后顺序时，若希望按完成顺序上送 span，可设 use_batch_processor=False
+# configure_tracer_provider(..., use_batch_processor=False)
 
 @traced  # 默认 record_io=True，会记录函数入参与返回值
 def my_function():
     ...
 
-# span_type 在装饰器或适配器中设置，不在此处；可关闭输入/输出：@traced(record_io=False)
+# 指定 span 名称；作为入口调用时，该 name 即为 root span name
 @traced(name="custom_span", span_type="model", attributes={"key": "value"})
 def another():
     ...
@@ -92,6 +94,13 @@ chain.invoke({"input": "..."}, config={"callbacks": [handler]})
 graph.invoke({"messages": [...]}, config={"callbacks": [handler]})
 ```
 
+**指定 Root Span 名称**：创建 handler 时传入 `root_span_name`，仅对根 run 生效。
+
+```python
+handler = get_langchain_callback(root_span_name="my_agent")
+graph.invoke(..., config={"callbacks": [handler]})
+```
+
 ### 手动上报（span_input / span_output）
 
 ```python

{mingx-0.1.0.dist-info → mingx-0.1.1.dist-info}/RECORD

@@ -1,15 +1,15 @@
 mingx/__init__.py,sha256=cTuHXXyEShdAzaApsgUYg_CA5DowqFWwMPUT45pbaB8,1482
 mingx/_default_attributes.py,sha256=UGs3IuPSlInTlseVeU7cZvITcSBQSpg4HYv7Fz5RzPM,2682
-mingx/_trace.py,sha256=8xSypFw2vgw4uJnLLiB8yiGOA0Ga3dDcDWaUhQlVkic,5534
-mingx/decorator.py,sha256=qKtSOI7eyHfhJeAc9-YApEBOHhhNif7efm0h3l-le_M,6638
+mingx/_trace.py,sha256=NJv--Kh4FjIYn--B8EiyM7_WYV2IC9IOIdsfW-t-E4E,5969
+mingx/decorator.py,sha256=nzTGp5SynFWCiy76cUbJOnUuP39SAw7dfMkyDmD4O2o,6947
 mingx/adapters/__init__.py,sha256=shSWbWvkQTn0-yh3iBQWBn5OICEV5uoDDwLhDf8Rovw,496
 mingx/adapters/base.py,sha256=hv0CPXgeBC0bxUtfnN-y0Q_jh7GxML9XxffK3CXB_34,2524
-mingx/adapters/langchain.py,sha256=ZvPWLibpVwn0BAKqYUB3eYx5-5ezcd8yvxy3qwYvFJA,26309
+mingx/adapters/langchain.py,sha256=dGvQktdGEsQJ8SaxT_keGazYBNRBXScpVoG2MT0kE7I,26917
 mingx/genai/__init__.py,sha256=G9ygXhaM_uTU5q0hZoVhDkhRSaSERoYK02isiPRnkvY,2612
 mingx/genai/attributes.py,sha256=ssRFX_YoyNNjYZrpct-Ixawtsz-zK6dlgR-7QgbVl8k,6376
 mingx/genai/io.py,sha256=m4tYrzR4Kk2KxSjHApCf90gdssZWlB_WCzuBk1pQ_9w,17393
 mingx/genai/span_attributes.py,sha256=UveEVnrXWNB10kk24dw0ZfVAxvxRNdmAyKJgk-FMfhs,5758
 mingx/genai/spans.py,sha256=DWSOis5o2en9r_UM8UNqpjIXMqOyC2ru8tnGa8POsww,5259
-mingx-0.1.0.dist-info/METADATA,sha256=ycRW6TuRNtgM4dyrSTLWkfNBB5xE5kqEp71jNyRqwVQ,14951
-mingx-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-mingx-0.1.0.dist-info/RECORD,,
+mingx-0.1.1.dist-info/METADATA,sha256=eOrELehyJu3VAxCYDwbuJF3nmdlAuOVDZ9Xi2zwwZx0,15324
+mingx-0.1.1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+mingx-0.1.1.dist-info/RECORD,,