Added SchedulerListener Instrumentation for Scheduler-level errors in Quartz

[angad-2]

Description

Adds scheduler-level instrumentation to the Quartz integration via org.quartz.SchedulerListener, addressing part of #14628.

A new TracingSchedulerListener (registered by QuartzTelemetry.configure) handles SchedulerListener.schedulerError. Since a scheduler error is a point-in-time occurrence with no duration, it is emitted as a log-based event (not a span):

• event name quartz.scheduler.exception, severity ERROR
• the Quartz error message as the log body
• the SchedulerException recorded via setException(...)
• a quartz.scheduler.name attribute (experimental — see below)

The scheduler name is also added to the existing job execution spans.

Design notes / scope

• Avoiding duplicate errors: Quartz also reports job execution failures through schedulerError, on the same thread while a job is running. That failure is already recorded on the job span, so emitting an event there would duplicate it. TracingJobListener sets a context marker while a job executes, and TracingSchedulerListener suppresses only when that marker is present — so genuine scheduler-level errors that occur under an unrelated span are still emitted.
• Experimental attributes: quartz.scheduler.name (a non-semconv attribute, on both the event and job spans) is only emitted when the existing captureExperimentalSpanAttributes option is enabled, consistent with how job.system is gated.
• Why an event, not a span: point-in-time occurrences fit the Logs/Events API better than a zero-duration span, matching how OTel log bridges map a message.
• Grouping DB spans: the issue also hoped SchedulerListener could group the DB spans Quartz emits internally. That isn't achievable here — these listener hooks are point-in-time events with no start/end bracket around the internal DB work, so there is no span to parent those queries to.

What's NOT included

• Additional JobListener/job-execution span attributes beyond the scheduler name — tracked separately in Include messaging attributes in Quartz spans #14624.
• Capturing the job span's exception as a log-based exception — good follow-up (see Add opt-in support for emitting exceptions as log signals #16259, Emit DB exceptions as logs under the opt-in preview #18889), out of scope here.

Testing

• New schedulerError test plus scheduler-name assertions on job spans in AbstractQuartzTest, exercised by both the library and javaagent modules, in the default and experimental-attribute runs.

[linux-foundation-easycla]

The committers listed above are authorized under a signed CLA.

• ✅ login: angad-2 / name: angad2212 (1f43834)

[Copilot]

Pull request overview

This PR extends the Quartz 2.0 instrumentation to emit spans for genuine scheduler-level errors reported through SchedulerListener.schedulerError, complementing the existing job-execution instrumentation. It registers a new TracingSchedulerListener from QuartzTelemetry.configure(Scheduler) (used by both the library and javaagent paths), backed by a dedicated Instrumenter<SchedulerError, Void>. To avoid double-recording, the listener skips emitting a span whenever a span is already active on the current thread (the case when Quartz surfaces a job failure through schedulerError).

Changes:

• Adds TracingSchedulerListener, SchedulerError, and SchedulerErrorAttributesExtractor (records quartz.scheduler.name), wired via a new scheduler-error Instrumenter in QuartzTelemetryBuilder.
• Registers the scheduler listener alongside the job listener in QuartzTelemetry.configure, mirroring the existing dedup/exception-handling pattern.
• Adds a schedulerError test in the shared AbstractQuartzTest covering both library and javaagent modules.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
.../TracingSchedulerListener.java	New listener that emits a span for genuine scheduler errors, skipping when a span is already active.
.../SchedulerError.java	New request object holding scheduler name and error message.
.../SchedulerErrorAttributesExtractor.java	Adds the quartz.scheduler.name attribute on span start.
.../QuartzTelemetryBuilder.java	Builds a dedicated scheduler-error instrumenter and passes it to QuartzTelemetry.
.../QuartzTelemetry.java	Registers the scheduler listener and stores the new instrumenter.
.../AbstractQuartzTest.java	Adds a schedulerError test asserting the produced span.

[opentelemetry-pr-dashboard]

Pull request dashboard status

Status last refreshed: 2026-07-21 23:34:07 UTC.

• Waiting on: Maintainers
• Next step: Merge when ready.

This automated status or its linked feedback items may be incorrect. If something looks wrong, report it with the result you expected.

[laurit]

@jaydeluca with this PR quartz instrumentation will emit an event in case you wish to add this to the collected metadata

[laurit]

Open question is whether emitting the event should be configurable or whether there is any reason why it shouldn't be emitted by default.

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 4 comments.

[Copilot]

Pull request overview

Copilot reviewed 13 out of 13 changed files in this pull request and generated 7 comments.

[Copilot]

Pull request overview

Copilot reviewed 13 out of 13 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (1)

instrumentation/quartz-2.0/javaagent/src/main/java/io/opentelemetry/javaagent/instrumentation/quartz/v2_0/QuartzSingletons.java:35

• [Testing] This one-release compatibility branch is not exercised: both testExperimental tasks now set only the replacement property, so a typo or translation regression in the deprecated key could ship while all Quartz tests pass. Add a javaagent test task using otel.instrumentation.quartz.experimental-span-attributes=true (and, if practical, verify the warning) to preserve the promised fallback until 3.0.

    // Support the deprecated config key until 3.0.
    Boolean deprecatedExperimentalSpanAttributes =
        config.getBoolean("experimental_span_attributes/development");

[Copilot]

Pull request overview

Copilot reviewed 14 out of 14 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 14 out of 14 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (1)

instrumentation/quartz-2.0/javaagent/src/main/java/io/opentelemetry/javaagent/instrumentation/quartz/v2_0/QuartzSingletons.java:31

• [Testing] The compatibility branch for the deprecated property is not exercised: both experimental test tasks were switched to the replacement property, so a typo or precedence regression here could silently break the promised one-release fallback. Add a dedicated test/task that configures otel.instrumentation.quartz.experimental-span-attributes and verifies experimental telemetry remains enabled; ideally also cover new-key precedence and the warning.

    // Support the deprecated config key until 3.0.
    Boolean deprecatedExperimentalSpanAttributes =
        config.getBoolean("experimental_span_attributes/development");

[angad-2]

suppress only the job-execution duplicate scheduler error