docs(monitoring): add tracing docs and OTLP setup guidance

crates/mofa-monitoring/README.md

@@ -39,6 +39,29 @@ metrics push exporter:
 mofa-monitoring = { version = "0.1", features = ["otlp-metrics"] }
 ```
 
+Required environment variables for OTLP exporters:
+
+```bash
+OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
+OTEL_SERVICE_NAME=mofa-service
+OTEL_EXPORTER_OTLP_PROTOCOL=grpc
+```
+
+## Getting Started: AgentTracer Integration
+
+```rust
+use std::sync::Arc;
+use mofa_monitoring::tracing::{
+	AgentTracer, ConsoleExporter, SimpleSpanProcessor, Tracer, TracerConfig, TracerProvider,
+};
+
+let exporter = Arc::new(ConsoleExporter::new());
+let processor = Arc::new(SimpleSpanProcessor::new(exporter));
+let provider = Arc::new(TracerProvider::new(TracerConfig::new("my-agent"), processor));
+let tracer = Arc::new(Tracer::new(provider));
+let _agent_tracer = AgentTracer::new(tracer);
+```
+
 ## Documentation
 
 - [API Documentation](https://docs.rs/mofa-monitoring)

crates/mofa-monitoring/src/tracing/mod.rs

@@ -5,6 +5,26 @@
 //! - Span management
 //! - Multiple exporters (Console, Jaeger, OTLP)
 //! - Automatic tracing for Agents and Workflows
+//!
+//! # Quick Start
+//!
+//! ```rust,ignore
+//! use std::sync::Arc;
+//! use mofa_monitoring::tracing::{
+//!     AgentTracer, ConsoleExporter, SimpleSpanProcessor, Tracer, TracerConfig, TracerProvider,
+//! };
+//!
+//! let exporter = Arc::new(ConsoleExporter::new());
+//! let processor = Arc::new(SimpleSpanProcessor::new(exporter));
+//! let provider = Arc::new(TracerProvider::new(TracerConfig::new("my-agent"), processor));
+//! let tracer = Arc::new(Tracer::new(provider));
+//! let _agent_tracer = AgentTracer::new(tracer);
+//! ```
+//!
+//! # Utility Helpers
+//!
+//! Use `trace_agent_operation` and `trace_workflow_execution` to attach tracing
+//! around custom logic blocks without manually creating and ending spans.
 
 mod context;
 mod exporter;

crates/mofa-monitoring/src/tracing/span.rs

@@ -58,6 +58,7 @@ pub enum SpanStatus {
     Ok,
     /// 错误
     /// Error
+    /// Failed operation with human-readable message.
     Error { message: String },
 }
 
@@ -66,13 +67,21 @@ pub enum SpanStatus {
 #[derive(Debug, Clone, Serialize, Deserialize)]
 #[serde(untagged)]
 pub enum SpanAttribute {
+    /// UTF-8 string attribute value.
     String(String),
+    /// Signed integer attribute value.
     Int(i64),
+    /// Floating-point attribute value.
     Float(f64),
+    /// Boolean attribute value.
     Bool(bool),
+    /// Array of UTF-8 string values.
     StringArray(Vec<String>),
+    /// Array of signed integer values.
     IntArray(Vec<i64>),
+    /// Array of floating-point values.
     FloatArray(Vec<f64>),
+    /// Array of boolean values.
     BoolArray(Vec<bool>),
 }
 
@@ -134,6 +143,7 @@ pub struct SpanEvent {
 }
 
 impl SpanEvent {
+    /// Create a span event using the current UTC timestamp.
     pub fn new(name: impl Into<String>) -> Self {
         Self {
             name: name.into(),
@@ -165,6 +175,7 @@ pub struct SpanLink {
 }
 
 impl SpanLink {
+    /// Create a link that associates this span with another span context.
     pub fn new(span_context: SpanContext) -> Self {
         Self {
             span_context,

crates/mofa-monitoring/src/tracing/tracer.rs

@@ -26,6 +26,7 @@ pub enum SamplingStrategy {
     AlwaysOff,
     /// 按概率采样
     /// Probabilistic sampling
+    /// Probability-based sampling where values are expected in `[0.0, 1.0]`.
     Probabilistic(f64),
     /// 基于速率限制采样
     /// Rate-limiting based sampling
@@ -36,6 +37,7 @@ pub enum SamplingStrategy {
     },
     /// 父级决定
     /// Parent-based decision
+    /// Reuse parent sampling decision when available; otherwise evaluate `root`.
     ParentBased { root: Box<SamplingStrategy> },
 }
 
@@ -148,23 +150,27 @@ impl Default for TracerConfig {
 }
 
 impl TracerConfig {
+    /// Create a tracer config for a specific service name.
     pub fn new(service_name: impl Into<String>) -> Self {
         Self {
             service_name: service_name.into(),
             ..Default::default()
         }
     }
 
+    /// Attach a semantic service version (e.g. `1.2.3`).
     pub fn with_version(mut self, version: impl Into<String>) -> Self {
         self.service_version = Some(version.into());
         self
     }
 
+    /// Attach deployment environment (e.g. `dev`, `staging`, `prod`).
     pub fn with_environment(mut self, env: impl Into<String>) -> Self {
         self.environment = Some(env.into());
         self
     }
 
+    /// Select which traces are sampled.
     pub fn with_sampling_strategy(mut self, strategy: SamplingStrategy) -> Self {
         self.sampling_strategy = strategy;
         self
@@ -196,6 +202,7 @@ pub struct SimpleSpanProcessor {
 }
 
 impl SimpleSpanProcessor {
+    /// Processor that exports each span immediately on end.
     pub fn new(exporter: Arc<dyn TracingExporter>) -> Self {
         Self { exporter }
     }
@@ -234,6 +241,10 @@ pub struct BatchSpanProcessor {
 }
 
 impl BatchSpanProcessor {
+    /// Processor that buffers spans and exports in batches.
+    ///
+    /// - `batch_size`: export once buffered span count reaches this size.
+    /// - `max_queue_size`: hard cap before additional spans are dropped.
     pub fn new(
         exporter: Arc<dyn TracingExporter>,
         batch_size: usize,