Skip to content

[Bug]: TelemetryTracer removed in 2.0.0-RC4 breaks TracerRegistry.register() — no migration path documented #1934

Description

@Buktal

Describe the bug

In 2.0.0-RC4, TelemetryTracer has been removed as part of the deprecated tracing layer cleanup. However, TracerRegistry.register() still accepts a Tracer argument, and there is no documented migration path for users who previously integrated Langfuse (or any OTLP backend) via TracerRegistry + TelemetryTracer.

Any application that references TelemetryTracer will fail to compile after upgrading to 2.0.0-RC4, with no guidance on how to migrate to OtelTracingMiddleware.

To Reproduce

  1. Use TracerRegistry.register(TelemetryTracer.builder()...build()) — the pattern shown in earlier framework examples:
TracerRegistry.register(
    TelemetryTracer.builder()
        .tracer(tracerProvider.get("agentscope-java", "2.0.0-RC4"))
        .build()
);
  1. Upgrade to 2.0.0-RC4.
  2. Run mvn compile.
  3. See error: cannot find symbol: class TelemetryTracer.

Expected behavior

Either:

  • A compile-time error with a clear @Deprecated Javadoc pointing to the replacement, or
  • A migration guide explaining how to move from TracerRegistry + TelemetryTracer to OtelTracingMiddleware.

The new recommended pattern should be documented — something like:

// 1. Build and register the SdkTracerProvider as the GlobalOpenTelemetry instance
SdkTracerProvider provider = SdkTracerProvider.builder()
    .addSpanProcessor(BatchSpanProcessor.builder(exporter).build())
    .build();
OpenTelemetrySdk sdk = OpenTelemetrySdk.builder()
    .setTracerProvider(provider)
    .buildAndRegisterGlobal();

// 2. Attach the middleware when constructing the agent — OtelTracingMiddleware
//    reads from GlobalOpenTelemetry automatically
ReActAgent agent = ReActAgent.builder()
    .name("assistant")
    .model(model)
    .middleware(new OtelTracingMiddleware())
    .build();

Error messages

[ERROR] cannot find symbol
  symbol:   class TelemetryTracer
  location: class cn.kst.kuaibuddy.agent.config.tracing.TracingConfig

Environment

  • AgentScope-Java Version: 2.0.0-RC4
  • Java Version: 21
  • OS: Windows 11

Additional context

TracerRegistry itself is also annotated @Deprecated(forRemoval = true, since = "2.0.0"), so the entire old tracing layer is going away. The missing piece is a public-facing migration guide (Javadoc on TracerRegistry, a CHANGELOG entry, or an updated example) that tells users what the equivalent OtelTracingMiddleware setup looks like end-to-end, including how to wire up a custom OTLP exporter (e.g., Langfuse with Authorization: Basic ... header).

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions