OpenTelemetry Google Cloud Trace Exporter

This package implements a SpanExporter that converts OpenTelemetry ReadableSpan objects into Google Cloud Trace’s wire format and ships them over gRPC using the generated Cloud Trace v2 proto client. It’s the Node.js counterpart to Google’s Python and Go Cloud Trace exporters, maintained inside the opentelemetry-operations-js monorepo alongside a matching Cloud Monitoring exporter, a Cloud Trace propagator, and a shared resource-mapping utility.

Authentication is handled transparently through google-auth-library — on Compute Engine, Cloud Run, GKE, or App Engine the exporter resolves the project ID and credentials automatically from the metadata server, while local development falls back to an explicit service-account key file or inline credentials. Span attributes and OpenTelemetry resource fields are transformed into Cloud Trace’s attribute and monitored-resource shapes, with an optional resourceFilter regexp controlling which resource attributes get forwarded.

As of this writing, the package carries a runtime deprecation warning and README notice: Google plans to archive it after October 30th, 2026 in favor of standard OTLP exporters (@opentelemetry/exporter-trace-otlp-http/-grpc) talking to Cloud Trace’s OTLP endpoint directly, with a migration guide provided in the repository.

What You Get

• A TraceExporter class implementing the standard OpenTelemetry SpanExporter interface, so it drops into any BatchSpanProcessor setup
• Automatic Google Cloud authentication via GoogleAuth, resolving project ID and credentials from the GCP metadata server with no configuration needed on Compute Engine, Cloud Run, GKE, or App Engine
• Span and resource attribute transformation into Cloud Trace’s wire format, including a configurable resourceFilter regexp for controlling which OpenTelemetry resource attributes get forwarded as trace labels
• A pre-generated gRPC client for the Cloud Trace v2 BatchWriteSpans API, built from the same protos Google’s other client libraries use
• Support for both keyfile-based and inline service-account credentials for authentication outside GCP environments
• An escape hatch to override the API endpoint, for private connectivity or regional routing scenarios

Common Use Cases

• Exporting distributed traces from a Node.js microservice running on Cloud Run, GKE, or Compute Engine directly into Google Cloud Trace’s UI without deploying a separate Collector
• Adding request-level tracing to an existing OpenTelemetry-instrumented Express, Fastify, or gRPC service that already targets Google Cloud for logging and monitoring
• Correlating trace data with Cloud Logging and Cloud Monitoring metrics by pairing this exporter with the sibling @google-cloud/opentelemetry-cloud-monitoring-exporter package
• Local development and testing of GCP-bound tracing pipelines using an explicit service-account key file instead of ambient metadata-server credentials
• Migrating an existing app off Stackdriver/Cloud Trace’s legacy client libraries onto standard OpenTelemetry instrumentation while keeping Cloud Trace as the backend

Under The Hood

Architecture The package is a single-purpose adapter: src/trace.ts defines TraceExporter, which implements OpenTelemetry’s SpanExporter interface (export/shutdown) and owns a GoogleAuth instance plus a lazily-constructed gRPC client (TraceService) built from a bundled protobuf definition (protos/protos.json) via @grpc/proto-loader. On construction it kicks off an async getProjectId() call so the credential/project resolution overlaps with the caller’s own startup rather than blocking the first export. src/transform.ts isolates the pure conversion logic — mapping ReadableSpan attributes, status, links, and OpenTelemetry Resource fields into Cloud Trace’s Span/AttributeMap shapes — keeping wire-format concerns out of the exporter class itself. src/types.ts and src/external-types.ts separate the internal gRPC-generated types from the small public options surface (TraceExporterOptions), and src/index.ts re-exports only the public pieces. The design mirrors the sibling Cloud Monitoring exporter in the same monorepo, sharing a @google-cloud/opentelemetry-resource-util package for resource-to-monitored-resource mapping rather than duplicating that logic. Tech Stack Written in TypeScript, compiled with tsc and linted via Google’s gts toolchain. Runtime dependencies are @grpc/grpc-js and @grpc/proto-loader for the gRPC transport, google-auth-library for GCP credential resolution, and the internal @google-cloud/opentelemetry-resource-util workspace package. It peer-depends on @opentelemetry/api, @opentelemetry/core, @opentelemetry/resources, and @opentelemetry/sdk-trace-base so it stays compatible with whatever OpenTelemetry SDK version the consuming app pins. The monorepo is managed with Lerna, and CI includes dedicated Cloud Build pipelines that exercise the exporter end-to-end against real Cloud Run, GKE, GCE, GAE, and Cloud Functions deployments. Code Quality Tests use Mocha with ts-mocha and sinon for stubbing GoogleAuth and the gRPC client, with nyc for coverage; test/exporter.test.ts and test/transform.test.ts together run several hundred lines of assertions covering constructor behavior, credential resolution, span transformation edge cases, and error paths. Errors are surfaced through the OpenTelemetry ExportResult/ExportResultCode contract rather than thrown, and diag.error/diag.debug calls give operators visibility without crashing the exporter. TypeScript’s gts config enforces consistent style and catches type errors at compile time; there’s no any-heavy escape hatching visible in the reviewed source. What Makes It Unique Rather than requiring users to run a separate OpenTelemetry Collector with a Cloud Trace exporter sidecar, this package lets a Node.js process ship spans straight to Cloud Trace in-process, using the same zero-config credential resolution Google’s other client libraries rely on. Its main differentiator today is that it’s being deliberately retired: Google is steering users toward the vendor-neutral OTLP exporters talking to Cloud Trace’s own OTLP ingestion endpoint instead of this GCP-specific wire format, which the maintainers document explicitly rather than silently abandoning the package.