Added SchedulerListener Instrumentation for Scheduler-level errors in Quartz

instrumentation/quartz-2.0/library/src/main/java/io/opentelemetry/instrumentation/quartz/v2_0/QuartzTelemetry.java

@@ -6,16 +6,19 @@
 package io.opentelemetry.instrumentation.quartz.v2_0;
 
 import io.opentelemetry.api.OpenTelemetry;
+import io.opentelemetry.instrumentation.api.instrumenter.Instrumenter;
 import org.quartz.JobKey;
 import org.quartz.JobListener;
 import org.quartz.Matcher;
 import org.quartz.Scheduler;
 import org.quartz.SchedulerException;
+import org.quartz.SchedulerListener;
 import org.quartz.impl.matchers.EverythingMatcher;
 
 /** Entrypoint for telemetry instrumentation of Quartz jobs. */
 public final class QuartzTelemetry {
   private final JobListener jobListener;
+  private final Instrumenter<SchedulerError, Void> schedulerErrorInstrumenter;
 
   /** Returns a new {@link QuartzTelemetry} configured with the given {@link OpenTelemetry}. */
   public static QuartzTelemetry create(OpenTelemetry openTelemetry) {
@@ -29,8 +32,10 @@ public static QuartzTelemetryBuilder builder(OpenTelemetry openTelemetry) {
     return new QuartzTelemetryBuilder(openTelemetry);
   }
 
-  QuartzTelemetry(JobListener jobListener) {
+  QuartzTelemetry(
+      JobListener jobListener, Instrumenter<SchedulerError, Void> schedulerErrorInstrumenter) {
     this.jobListener = jobListener;
+    this.schedulerErrorInstrumenter = schedulerErrorInstrumenter;
   }
 
   /**
@@ -42,6 +47,11 @@ public static QuartzTelemetryBuilder builder(OpenTelemetry openTelemetry) {
    * not throw exceptions.
    */
   public void configure(Scheduler scheduler) {
+    addJobListener(scheduler);
+    addSchedulerListener(scheduler);
+  }
+
+  private void addJobListener(Scheduler scheduler) {
     try {
       for (JobListener listener : scheduler.getListenerManager().getJobListeners()) {
         if (listener instanceof TracingJobListener) {
@@ -61,4 +71,27 @@ public void configure(Scheduler scheduler) {
       throw new IllegalStateException("Could not add JobListener to Scheduler", e);
     }
   }
+
+  private void addSchedulerListener(Scheduler scheduler) {
+    try {
+      for (SchedulerListener listener : scheduler.getListenerManager().getSchedulerListeners()) {
+        if (listener instanceof TracingSchedulerListener) {
+          return;
+        }
+      }
+    } catch (SchedulerException ignored) {
+      // Ignore
+    }
+    try {
+      // The scheduler name is only available here (at configuration time), so we capture it now
+      // and hand it to the listener to use as a span attribute.
+      String schedulerName = scheduler.getSchedulerName();
+      scheduler
+          .getListenerManager()
+          .addSchedulerListener(
+              new TracingSchedulerListener(schedulerErrorInstrumenter, schedulerName));
+    } catch (SchedulerException e) {
+      throw new IllegalStateException("Could not add SchedulerListener to Scheduler", e);
+    }
+  }
 }

instrumentation/quartz-2.0/library/src/main/java/io/opentelemetry/instrumentation/quartz/v2_0/QuartzTelemetryBuilder.java

@@ -91,6 +91,16 @@ public QuartzTelemetry build() {
         CodeAttributesExtractor.create(new QuartzCodeAttributesGetter()));
     instrumenter.addAttributesExtractors(additionalExtractors);
 
-    return new QuartzTelemetry(new TracingJobListener(instrumenter.buildInstrumenter()));
+    // Separate instrumenter for scheduler-level events: the request type differs from job
+    // execution, and these are point-in-time events rather than start/end-bracketed work.
+    Instrumenter<SchedulerError, Void> schedulerErrorInstrumenter =
+        Instrumenter.<SchedulerError, Void>builder(
+                openTelemetry, INSTRUMENTATION_NAME, request -> "Quartz scheduler error")
+            .setErrorCauseExtractor(new QuartzErrorCauseExtractor())
+            .addAttributesExtractor(new SchedulerErrorAttributesExtractor())
+            .buildInstrumenter();
+
+    return new QuartzTelemetry(
+        new TracingJobListener(instrumenter.buildInstrumenter()), schedulerErrorInstrumenter);
   }
 }

instrumentation/quartz-2.0/library/src/main/java/io/opentelemetry/instrumentation/quartz/v2_0/SchedulerError.java

@@ -0,0 +1,33 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.instrumentation.quartz.v2_0;
+
+import javax.annotation.Nullable;
+
+/**
+ * A scheduler-level error reported by Quartz through {@code SchedulerListener.schedulerError}. This
+ * is the "request" object that drives the scheduler-error {@link
+ * io.opentelemetry.instrumentation.api.instrumenter.Instrumenter}.
+ */
+final class SchedulerError {
+
+  private final String schedulerName;
+  @Nullable private final String message;
+
+  SchedulerError(String schedulerName, @Nullable String message) {
+    this.schedulerName = schedulerName;
+    this.message = message;
+  }
+
+  String getSchedulerName() {
+    return schedulerName;
+  }
+
+  @Nullable
+  String getMessage() {
+    return message;
+  }
+}

instrumentation/quartz-2.0/library/src/main/java/io/opentelemetry/instrumentation/quartz/v2_0/SchedulerErrorAttributesExtractor.java

@@ -0,0 +1,32 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.instrumentation.quartz.v2_0;
+
+import io.opentelemetry.api.common.AttributeKey;
+import io.opentelemetry.api.common.AttributesBuilder;
+import io.opentelemetry.context.Context;
+import io.opentelemetry.instrumentation.api.instrumenter.AttributesExtractor;
+import javax.annotation.Nullable;
+
+final class SchedulerErrorAttributesExtractor implements AttributesExtractor<SchedulerError, Void> {
+
+  // Experimental attribute: name/shape may change until scheduler instrumentation stabilizes.
+  private static final AttributeKey<String> SCHEDULER_NAME =
+      AttributeKey.stringKey("quartz.scheduler.name");
+
+  @Override
+  public void onStart(AttributesBuilder attributes, Context parentContext, SchedulerError request) {
+    attributes.put(SCHEDULER_NAME, request.getSchedulerName());
+  }
+
+  @Override
+  public void onEnd(
+      AttributesBuilder attributes,
+      Context context,
+      SchedulerError request,
+      @Nullable Void response,
+      @Nullable Throwable error) {}
+}

instrumentation/quartz-2.0/library/src/main/java/io/opentelemetry/instrumentation/quartz/v2_0/TracingSchedulerListener.java

@@ -0,0 +1,52 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.instrumentation.quartz.v2_0;
+
+import io.opentelemetry.api.trace.Span;
+import io.opentelemetry.context.Context;
+import io.opentelemetry.instrumentation.api.instrumenter.Instrumenter;
+import org.quartz.SchedulerException;
+import org.quartz.listeners.SchedulerListenerSupport;
+
+/**
+ * Instruments scheduler-level Quartz events. Extends {@link SchedulerListenerSupport} so we only
+ * override the hooks we care about; every other {@code SchedulerListener} method defaults to a
+ * no-op and is available as an extension point for future events.
+ */
+final class TracingSchedulerListener extends SchedulerListenerSupport {
+
+  private final Instrumenter<SchedulerError, Void> instrumenter;
+  private final String schedulerName;
+
+  TracingSchedulerListener(Instrumenter<SchedulerError, Void> instrumenter, String schedulerName) {
+    this.instrumenter = instrumenter;
+    this.schedulerName = schedulerName;
+  }
+
+  @Override
+  public void schedulerError(String msg, SchedulerException cause) {
+    Context parentContext = Context.current();
+
+    // Quartz also reports job execution failures through schedulerError, on the same thread while
+    // the job execution span is still current. That failure is already recorded on the job span, so
+    // emitting another span here would just duplicate it. Only instrument genuine scheduler-level
+    // errors, i.e. when no span is currently active.
+    if (Span.fromContext(parentContext).getSpanContext().isValid()) {
+      return;
+    }
+
+    SchedulerError request = new SchedulerError(schedulerName, msg);
+    if (!instrumenter.shouldStart(parentContext, request)) {
+      return;
+    }
+
+    // schedulerError is a point-in-time event with no start/end bracket around work, so we start
+    // and immediately end a span that records the failure. The span has no children but surfaces
+    // the scheduler error (and the SchedulerException) in traces.
+    Context context = instrumenter.start(parentContext, request);
+    instrumenter.end(context, request, null, cause);
+  }
+}

instrumentation/quartz-2.0/testing/src/main/java/io/opentelemetry/instrumentation/quartz/v2_0/AbstractQuartzTest.java

@@ -32,6 +32,7 @@
 import org.quartz.JobExecutionContext;
 import org.quartz.Scheduler;
 import org.quartz.SchedulerException;
+import org.quartz.SchedulerListener;
 import org.quartz.Trigger;
 import org.quartz.impl.StdSchedulerFactory;
 
@@ -141,4 +142,28 @@ public void execute(JobExecutionContext context) {
       throw new IllegalStateException("Bad job");
     }
   }
+
+  @Test
+  void schedulerError() throws SchedulerException {
+    SchedulerException cause = new SchedulerException("boom");
+
+    // A real scheduler error is hard to provoke deterministically in a unit test, so we invoke the
+    // registered SchedulerListener directly to verify the span it produces.
+    for (SchedulerListener listener : scheduler.getListenerManager().getSchedulerListeners()) {
+      listener.schedulerError("Something went wrong", cause);
+    }
+
+    getTesting()
+        .waitAndAssertTraces(
+            trace ->
+                trace.hasSpansSatisfyingExactly(
+                    span ->
+                        span.hasName("Quartz scheduler error")
+                            .hasKind(SpanKind.INTERNAL)
+                            .hasNoParent()
+                            .hasStatus(StatusData.error())
+                            .hasException(cause)
+                            .hasAttributesSatisfyingExactly(
+                                equalTo(stringKey("quartz.scheduler.name"), "default"))));
+  }
 }