Add client-side telemetry hooks with OpenTelemetry integration

Adds a complete telemetry infrastructure that lets users hook into the
SDK's HTTP request lifecycle, integrate with OpenTelemetry for
tracing/metrics, and use Python's standard logging -- all opt-in with
zero overhead when disabled.

Key components:
- TelemetryConfig: frozen dataclass for configuring signals and hooks
- TelemetryHook: concrete base class for custom telemetry integrations
- TelemetryManager / NoOpTelemetryManager: instrumentation engine with
  factory that returns a zero-overhead no-op when telemetry is disabled
- RequestContext / ResponseContext: typed data passed to hooks
- _operation_scope: ContextVar-based mechanism to propagate operation
  names (e.g. "records.create") from namespace methods to _request()

Design improvements over the initial draft:
- TelemetryHook as concrete base class (not broken @runtime_checkable Protocol)
- _span removed from user-facing RequestContext (kept internal via _TrackedRequest)
- No except block in trace_request() -- eliminates double error dispatch
- Per-subsystem try/except in record_response() for exception safety
- NoOp yields None for true zero allocation overhead
- Explicit span status (OK/ERROR) on every response
- Safe log_level parsing with fallback

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: tpellissier

examples/telemetry_demo.py

@@ -0,0 +1,173 @@
+"""
+Telemetry Demo - Demonstrates OpenTelemetry integration with Dataverse SDK.
+
+This script shows telemetry flowing through:
+1. Custom hooks (always -- no extra dependencies)
+2. Console span/metric exporters (requires opentelemetry-sdk)
+3. Jaeger UI via OTLP (optional, if running locally via Docker)
+
+To run with hooks only (no OTel dependency):
+    python examples/telemetry_demo.py
+
+To run with full OTel:
+    pip install "PowerPlatform-Dataverse-Client[telemetry]"
+    pip install opentelemetry-sdk
+    python examples/telemetry_demo.py
+
+To run Jaeger locally:
+    docker run -d --name jaeger -p 16686:16686 -p 4317:4317 -p 4318:4318 jaegertracing/all-in-one:latest
+
+Then open http://localhost:16686 to see traces.
+
+Usage:
+    python examples/telemetry_demo.py
+"""
+
+import sys
+from pathlib import Path
+
+# Add src to path for development
+sys.path.insert(0, str(Path(__file__).parent.parent / "src"))
+
+# =============================================================================
+# OpenTelemetry Setup (optional -- demo works with hooks alone)
+# =============================================================================
+
+OTEL_CONFIGURED = False
+
+try:
+    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 ConsoleMetricExporter, PeriodicExportingMetricReader
+    from opentelemetry.sdk.resources import Resource
+
+    resource = Resource.create({"service.name": "dataverse-telemetry-demo"})
+
+    tracer_provider = TracerProvider(resource=resource)
+    tracer_provider.add_span_processor(BatchSpanProcessor(ConsoleSpanExporter()))
+
+    # Try OTLP exporter for Jaeger
+    try:
+        from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
+
+        tracer_provider.add_span_processor(
+            BatchSpanProcessor(OTLPSpanExporter(endpoint="http://localhost:4317", insecure=True))
+        )
+        print("OTLP exporter configured - view traces at http://localhost:16686")
+    except ImportError:
+        pass
+
+    trace.set_tracer_provider(tracer_provider)
+
+    metric_reader = PeriodicExportingMetricReader(ConsoleMetricExporter(), export_interval_millis=5000)
+    metrics.set_meter_provider(MeterProvider(resource=resource, metric_readers=[metric_reader]))
+
+    OTEL_CONFIGURED = True
+    print("OpenTelemetry configured with Console exporter")
+
+except ImportError:
+    print("OpenTelemetry not installed -- running with hooks only")
+    print("  Install with: pip install opentelemetry-sdk opentelemetry-api")
+
+print("-" * 60)
+
+# =============================================================================
+# Dataverse SDK Setup
+# =============================================================================
+
+from PowerPlatform.Dataverse.client import DataverseClient
+from PowerPlatform.Dataverse.core.config import DataverseConfig
+from PowerPlatform.Dataverse.core.telemetry import TelemetryConfig, TelemetryHook
+from azure.identity import InteractiveBrowserCredential
+
+# Org details
+ORG_URL = "https://aurorabapenvcc726.crmtest.dynamics.com"
+TENANT_ID = "91bee3d9-0c15-4f17-8624-c92bb8b36ead"
+
+
+class DemoTelemetryHook(TelemetryHook):
+    """Custom hook that prints request/response info to the console."""
+
+    def on_request_start(self, ctx):
+        print(f"\n>>> Starting: {ctx.operation} [{ctx.method}]")
+        if ctx.table_name:
+            print(f"    Table: {ctx.table_name}")
+
+    def on_request_end(self, request, response):
+        status = "[OK]" if response.status_code < 400 else "[ERR]"
+        print(f"<<< {status} {request.operation} - {response.status_code} in {response.duration_ms:.1f}ms")
+        if response.service_request_id:
+            print(f"    Service Request ID: {response.service_request_id}")
+
+    def on_request_error(self, request, error):
+        print(f"!!! Error in {request.operation}: {error}")
+
+
+def main():
+    print("\n" + "=" * 60)
+    print("DATAVERSE TELEMETRY DEMO")
+    print("=" * 60)
+
+    config = DataverseConfig(
+        telemetry=TelemetryConfig(
+            enable_tracing=OTEL_CONFIGURED,
+            enable_metrics=OTEL_CONFIGURED,
+            enable_logging=True,
+            log_level="DEBUG",
+            hooks=[DemoTelemetryHook()],
+        )
+    )
+
+    print(f"\nConnecting to: {ORG_URL}")
+    print("(Browser will open for authentication)\n")
+
+    credential = InteractiveBrowserCredential(tenant_id=TENANT_ID)
+    client = DataverseClient(ORG_URL, credential, config=config)
+
+    # ---- Operation 1: Query accounts ----
+    print("\n" + "-" * 60)
+    print("OPERATION 1: Query accounts (top 3)")
+    print("-" * 60)
+
+    for page in client.records.get("account", select=["name", "accountid"], top=3):
+        print(f"\nFound {len(page)} accounts:")
+        for record in page:
+            print(f"  - {record.get('name', 'N/A')} ({record.get('accountid', 'N/A')[:8]}...)")
+
+    # ---- Operation 2: SQL query ----
+    print("\n" + "-" * 60)
+    print("OPERATION 2: SQL query for contacts")
+    print("-" * 60)
+
+    rows = client.query.sql("SELECT TOP 3 fullname, emailaddress1 FROM contact ORDER BY fullname")
+    print(f"\nFound {len(rows)} contacts:")
+    for row in rows:
+        print(f"  - {row.get('fullname', 'N/A')} <{row.get('emailaddress1', 'N/A')}>")
+
+    # ---- Operation 3: Table metadata ----
+    print("\n" + "-" * 60)
+    print("OPERATION 3: Get table metadata")
+    print("-" * 60)
+
+    info = client.tables.get("account")
+    if info:
+        print(f"\nTable: {info.get('table_schema_name')}")
+        print(f"  Logical: {info.get('table_logical_name')}")
+        print(f"  Entity Set: {info.get('entity_set_name')}")
+
+    print("\n" + "=" * 60)
+    print("DEMO COMPLETE")
+    print("=" * 60)
+    print("\nCheck the console output above for:")
+    print("  - Hook output (>>> / <<< lines)")
+    if OTEL_CONFIGURED:
+        print("  - Span traces (name, attributes, duration)")
+        print("  - Metrics (request counts, durations)")
+        print("\nIf Jaeger is running, view traces at: http://localhost:16686")
+    print()
+
+
+if __name__ == "__main__":
+    main()

pyproject.toml

@@ -49,6 +49,10 @@ dev = [
     "mypy>=1.0.0",
     "ruff>=0.1.0",
 ]
+telemetry = [
+    "opentelemetry-api>=1.20.0",
+    "opentelemetry-sdk>=1.20.0",
+]
 
 [tool.setuptools]
 package-dir = {"" = "src"}

src/PowerPlatform/Dataverse/common/constants.py

@@ -29,3 +29,34 @@
 
 CASCADE_BEHAVIOR_RESTRICT = "Restrict"
 """Prevent the referenced table record from being deleted when referencing table records exist."""
+
+
+# OpenTelemetry semantic convention attribute names
+# See: https://opentelemetry.io/docs/specs/semconv/
+
+OTEL_ATTR_DB_SYSTEM = "db.system"
+"""Database system identifier."""
+
+OTEL_ATTR_DB_OPERATION = "db.operation"
+"""Database operation name."""
+
+OTEL_ATTR_HTTP_METHOD = "http.request.method"
+"""HTTP request method."""
+
+OTEL_ATTR_HTTP_URL = "url.full"
+"""Full HTTP request URL."""
+
+OTEL_ATTR_HTTP_STATUS_CODE = "http.response.status_code"
+"""HTTP response status code."""
+
+OTEL_ATTR_DATAVERSE_TABLE = "dataverse.table"
+"""Dataverse table (entity) name."""
+
+OTEL_ATTR_DATAVERSE_REQUEST_ID = "dataverse.client_request_id"
+"""Client-generated request ID (x-ms-client-request-id header)."""
+
+OTEL_ATTR_DATAVERSE_CORRELATION_ID = "dataverse.correlation_id"
+"""Client-generated correlation ID (x-ms-correlation-id header)."""
+
+OTEL_ATTR_DATAVERSE_SERVICE_REQUEST_ID = "dataverse.service_request_id"
+"""Server-assigned request ID (x-ms-service-request-id header)."""

src/PowerPlatform/Dataverse/core/config.py

@@ -12,7 +12,10 @@
 from __future__ import annotations
 
 from dataclasses import dataclass
-from typing import Optional
+from typing import Optional, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .telemetry import TelemetryConfig
 
 
 @dataclass(frozen=True)
@@ -28,6 +31,9 @@ class DataverseConfig:
     :type http_backoff: :class:`float` or None
     :param http_timeout: Optional request timeout in seconds. Reserved for future use.
     :type http_timeout: :class:`float` or None
+    :param telemetry: Optional telemetry configuration for tracing, metrics, logging, and custom hooks.
+        When ``None`` (the default) telemetry is disabled with zero overhead.
+    :type telemetry: ~PowerPlatform.Dataverse.core.telemetry.TelemetryConfig or None
     """
 
     language_code: int = 1033
@@ -37,6 +43,9 @@ class DataverseConfig:
     http_backoff: Optional[float] = None
     http_timeout: Optional[float] = None
 
+    # Telemetry configuration (opt-in; None = disabled)
+    telemetry: Optional[TelemetryConfig] = None
+
     @classmethod
     def from_env(cls) -> "DataverseConfig":
         """