@clipboard-health/mongo-jobs 0.1.0

package/src/lib/tracing.js

@@ -0,0 +1,194 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withProducerTrace = withProducerTrace;
+exports.withConsumerTrace = withConsumerTrace;
+exports.withInternalsTrace = withInternalsTrace;
+const api_1 = require("@opentelemetry/api");
+// According to the OpenTelemetry spec, the span name should follow the pattern of
+//   <destination name> <operation name>
+// Where destination is the name of the queue and operation is the action being performed
+//
+// https://opentelemetry.io/docs/reference/specification/trace/semantic_conventions/messaging/#span-name
+const TRACER_NAME = "mongo-jobs";
+const PRODUCER_SPAN = "background-jobs.producer";
+const CONSUMER_SPAN = "background-jobs.consumer";
+const INTERNALS_SPAN = "background-jobs.internals";
+const Component = {
+    BACKGROUND_JOBS: "background-jobs",
+};
+const Operation = {
+    PROCESS: "process",
+    PUBLISH: "publish",
+};
+const MessagingSystem = {
+    MONGO: "mongo-jobs",
+};
+const MessagingDestinationKind = {
+    QUEUE: "queue",
+};
+function resourceName(operation, destination) {
+    return `${operation} ${destination}`;
+}
+/**
+ * Inject trace context into headers for propagation.
+ * This allows child spans to link back to the current parent span.
+ */
+function injectTraceHeaders() {
+    const traceHeaders = {};
+    api_1.propagation.inject(api_1.context.active(), traceHeaders);
+    return traceHeaders;
+}
+/**
+ * Extract trace context from headers to link spans.
+ * Returns a context with the parent span information.
+ */
+function extractTraceContext(traceHeaders) {
+    if (!traceHeaders) {
+        return api_1.context.active();
+    }
+    return api_1.propagation.extract(api_1.context.active(), traceHeaders);
+}
+/**
+ * Create attributes for a producer telemetry span.
+ *
+ * Attributes definition for background jobs are still in RFC
+ * in the meantime, we should use the `messaging` convention
+ *
+ * Issue containing the RFC:
+ *  - https://github.com/open-telemetry/opentelemetry-specification/pull/1582#issue-842434527
+ *
+ * Datadog supports the `messaging` convention:
+ * - https://docs.datadoghq.com/tracing/trace_collection/tracing_naming_convention#message-queue
+ */
+function producerAttributes(job) {
+    return {
+        component: Component.BACKGROUND_JOBS,
+        "messaging.system": MessagingSystem.MONGO,
+        "messaging.operation": Operation.PUBLISH,
+        "messaging.destination": job.handlerName,
+        "messaging.destination_kind": MessagingDestinationKind.QUEUE,
+        "messaging.mongo-bg-jobs.queue": job.queue ?? "unknown",
+        "resource.name": resourceName(Operation.PUBLISH, job.handlerName),
+    };
+}
+function consumerAttributes(job) {
+    return {
+        component: Component.BACKGROUND_JOBS,
+        "span.type": "worker",
+        "messaging.system": MessagingSystem.MONGO,
+        "messaging.operation": Operation.PROCESS,
+        "messaging.message_id": job._id.toString(),
+        "messaging.destination": job.handlerName,
+        "messaging.destination_kind": MessagingDestinationKind.QUEUE,
+        "messaging.mongo-bg-jobs.queue": job.queue ?? "unknown",
+        "messaging.mongo-bg-jobs.attemptsCount": job.attemptsCount.toString(),
+        "messaging.mongo-bg-jobs.createdAt": job.createdAt.toISOString(),
+        "messaging.mongo-bg-jobs.updatedAt": job.updatedAt.toISOString(),
+        "messaging.mongo-bg-jobs.nextRunAt": job.nextRunAt?.toISOString() ?? "",
+        "messaging.mongo-bg-jobs.lockedAt": job.lockedAt?.toISOString() ?? "",
+        "messaging.mongo-bg-jobs.failedAt": job.failedAt?.toISOString() ?? "",
+        "resource.name": resourceName(Operation.PROCESS, job.handlerName),
+    };
+}
+function isCronJob(job) {
+    return job.scheduleName !== undefined;
+}
+async function withProducerTrace(handler, data, callback) {
+    const tracer = api_1.trace.getTracer(TRACER_NAME);
+    const handlerName = handler.name;
+    return await tracer.startActiveSpan(PRODUCER_SPAN, {
+        kind: api_1.SpanKind.PRODUCER,
+        attributes: {
+            "resource.name": resourceName(Operation.PUBLISH, handlerName),
+        },
+    }, async (span) => {
+        try {
+            // Inject trace context for distributed tracing
+            const traceHeaders = injectTraceHeaders();
+            const job = await callback({ ...data, _traceHeaders: traceHeaders });
+            if (job) {
+                span.setAttributes(producerAttributes(job));
+            }
+            span.setStatus({ code: api_1.SpanStatusCode.OK });
+            return job;
+        }
+        catch (error) {
+            span.setStatus({
+                code: api_1.SpanStatusCode.ERROR,
+                message: error instanceof Error ? error.message : String(error),
+            });
+            span.recordException(error);
+            throw error;
+        }
+        finally {
+            span.end();
+        }
+    });
+}
+async function executeJobTrace(tracer, attributes, parentContext, callback) {
+    await tracer.startActiveSpan(CONSUMER_SPAN, {
+        kind: api_1.SpanKind.CONSUMER,
+        attributes,
+    }, parentContext, async (span) => {
+        try {
+            await callback();
+            span.setStatus({ code: api_1.SpanStatusCode.OK });
+        }
+        catch (error) {
+            span.setStatus({
+                code: api_1.SpanStatusCode.ERROR,
+                message: error instanceof Error ? error.message : String(error),
+            });
+            span.recordException(error);
+            throw error;
+        }
+        finally {
+            span.end();
+        }
+    });
+}
+async function withConsumerTrace(job, callback) {
+    const tracer = api_1.trace.getTracer(TRACER_NAME);
+    const attributes = consumerAttributes(job);
+    let parentContext;
+    if (isCronJob(job)) {
+        /**
+         * We need to manually remove the context of traces for cron jobs.
+         * Otherwise cron jobs traces are shown in the context of the entire worker and they
+         * are not very pleasant to look at in Datadog (sometimes impossible).
+         **/
+        parentContext = api_1.ROOT_CONTEXT;
+    }
+    else {
+        const jobData = job.data || {};
+        parentContext = extractTraceContext(jobData._traceHeaders);
+    }
+    await executeJobTrace(tracer, attributes, parentContext, callback);
+}
+async function withInternalsTrace(resource, callback) {
+    const tracer = api_1.trace.getTracer(TRACER_NAME);
+    return await tracer.startActiveSpan(INTERNALS_SPAN, {
+        kind: api_1.SpanKind.INTERNAL,
+        attributes: {
+            "resource.name": resource,
+        },
+    }, async (span) => {
+        try {
+            const result = await callback();
+            span.setStatus({ code: api_1.SpanStatusCode.OK });
+            return result;
+        }
+        catch (error) {
+            span.setStatus({
+                code: api_1.SpanStatusCode.ERROR,
+                message: error instanceof Error ? error.message : String(error),
+            });
+            span.recordException(error);
+            throw error;
+        }
+        finally {
+            span.end();
+        }
+    });
+}
+//# sourceMappingURL=tracing.js.map

package/src/lib/tracing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracing.js","sourceRoot":"","sources":["../../../../../packages/mongo-jobs/src/lib/tracing.ts"],"names":[],"mappings":"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"}