feat: Otel Observabillity

[tymondesigns]

This pull request introduces OpenTelemetry-based distributed tracing to the Cortex framework, allowing detailed tracking of agent runs, LLM calls, tool executions, and middleware steps. It also adds new middleware event types for better observability and updates the configuration and dependencies to support these features. Additionally, it improves middleware wrappers to emit lifecycle events and makes a minor update to the default LLM for the WeatherAgent.

Distributed Tracing and Observability:

• OpenTelemetry Integration:
  • Adds OpenTelemetry PHP SDK dependencies and configuration options to composer.json and config/cortex.php, enabling tracing export to any OTLP-compatible backend (e.g., Jaeger, Tempo, Honeycomb, Datadog).
    [1] [2] [3] [4]
  • Implements setupTracing() in CortexServiceProvider to initialize the tracer provider and subscribe a new OpenTelemetrySubscriber for event dispatching.

Middleware Lifecycle Events:

• New Event Types:

  • Introduces MiddlewareStart, MiddlewareEnd, and MiddlewareError events, along with a MiddlewareEvent interface, to represent the lifecycle of middleware execution.
    [1] [2] [3] [4]

• Event Dispatching in Middleware Wrappers:

  • Updates BeforePromptWrapper, BeforeModelWrapper, and AfterModelWrapper to dispatch the new lifecycle events at the start, end, and on error of each middleware invocation, improving traceability and error reporting.
    [1] [2] [3] [4] [5] [6]

Other Notable Changes:

• LLM Tool Configuration:

  • Adds a getToolConfig() method to the LLM interface and its abstract base class, allowing retrieval of tool configuration for LLMs.
    [1] [2] [3]

• Default LLM Update:

  • Changes the default LLM in WeatherAgent from ollama/qwen3.5:9b to lmstudio/openai/gpt-oss-20b.

• Composer Plugin Allowance:

  • Allows the tbachert/spi plugin in composer.json for dependency management.

These changes collectively enhance the framework's observability, making it easier to monitor, debug, and analyze agent and middleware behavior in production environments.