@google-cloud/opentelemetry-cloud-trace-exporter

What is @google-cloud/opentelemetry-cloud-trace-exporter?

@google-cloud/opentelemetry-cloud-trace-exporter is an npm package that allows you to export OpenTelemetry traces to Google Cloud Trace. This package is useful for monitoring and debugging applications by providing detailed trace data that can be analyzed in Google Cloud's suite of monitoring tools.

What are @google-cloud/opentelemetry-cloud-trace-exporter's main functionalities?

Initialize the Exporter

This code initializes the Google Cloud Trace Exporter with the necessary project ID and key file for authentication.

const { TraceExporter } = require('@google-cloud/opentelemetry-cloud-trace-exporter');
const exporter = new TraceExporter({
  projectId: 'your-project-id',
  keyFilename: '/path/to/keyfile.json'
});

Set up OpenTelemetry SDK

This code sets up the OpenTelemetry SDK and registers the Google Cloud Trace Exporter as a span processor.

const { NodeTracerProvider } = require('@opentelemetry/node');
const { SimpleSpanProcessor } = require('@opentelemetry/tracing');
const provider = new NodeTracerProvider();
provider.addSpanProcessor(new SimpleSpanProcessor(exporter));
provider.register();

Create and Export Traces

This code demonstrates how to create and export a trace using the OpenTelemetry API. The span created will be exported to Google Cloud Trace.

const { trace } = require('@opentelemetry/api');
const tracer = trace.getTracer('example-tracer');
const span = tracer.startSpan('example-span');
// Do some work
span.end();

Other packages similar to @google-cloud/opentelemetry-cloud-trace-exporter

@opentelemetry/exporter-jaeger

This package exports OpenTelemetry traces to Jaeger, an open-source, end-to-end distributed tracing tool. It is similar to @google-cloud/opentelemetry-cloud-trace-exporter but is used for exporting traces to Jaeger instead of Google Cloud Trace.

@opentelemetry/exporter-zipkin

This package exports OpenTelemetry traces to Zipkin, another open-source distributed tracing system. Like @google-cloud/opentelemetry-cloud-trace-exporter, it helps in exporting trace data but targets Zipkin for trace visualization and analysis.

@opentelemetry/exporter-collector

This package exports OpenTelemetry traces to the OpenTelemetry Collector, a vendor-agnostic service that can export data to various backends including Google Cloud Trace, Jaeger, and Zipkin. It provides more flexibility compared to @google-cloud/opentelemetry-cloud-trace-exporter by supporting multiple backends.

README

OpenTelemetry Google Cloud Trace Exporter

OpenTelemetry Google Cloud Trace Exporter allows the user to send collected traces to Google Cloud.

Google Cloud Trace is a distributed tracing system. It helps gather timing data needed to troubleshoot latency problems in microservice architectures. It manages both the collection and lookup of this data.

Setup

Google Cloud Trace is a managed service provided by Google Cloud Platform.

Installation

npm install --save @google-cloud/opentelemetry-cloud-trace-exporter

Usage

Install the exporter on your application, register the exporter, and start tracing. If you are running in a GCP environment, the exporter will automatically authenticate using the environment's service account. If not, you will need to follow the instructions in Authentication.

const { TraceExporter } = require('@google-cloud/opentelemetry-cloud-trace-exporter');

const exporter = new TraceExporter({
  // If you are not in a GCP environment, you will need to provide your
  // service account key here. See the Authentication section below.
});

Now, register the exporter with the built-in BatchSpanProcessor which batches ended spans and passes them to the configured SpanExporter.

provider.addSpanProcessor(new BatchSpanProcessor(exporter));

Resource attributes

By default, OpenTelemetry resource attributes which do not map to a monitored resource are ignored. If you wish to export other resource attributes, you must specify a regexp that should match the attribute keys you'd like.

For example, if you are setting up a resource with the "service" semantic attributes:

const {
  SEMRESATTRS_SERVICE_NAME,
  SEMRESATTRS_SERVICE_NAMESPACE,
  SEMRESATTRS_SERVICE_VERSION,
  SEMRESATTRS_SERVICE_INSTANCE_ID,
} = require('@opentelemetry/semantic-conventions');

const provider = new NodeTracerProvider({
  // ...
  resource: new Resource({

  SEMRESATTRS_SERVICE_NAME,
    [SEMRESATTRS_SERVICE_NAME]: 'things-service',
    [SEMRESATTRS_SERVICE_NAMESPACE]: 'things',
    [SEMRESATTRS_SERVICE_VERSION]: '1.0.0',
    [SEMRESATTRS_SERVICE_INSTANCE_ID]: 'abc123',
  }),
})

You can ensure they are exported by using a regexp that matches them:

const exporter = new TraceExporter({
  // will export all resource attributes that start with "service."
  resourceFilter: /^service\./
});

Authentication

The Google Cloud Trace exporter supports authentication using service accounts. These can either be defined in a keyfile (usually called service_account_key.json or similar), or by the environment. If your application runs in a GCP environment, such as Compute Engine, you don't need to provide any application credentials. The client library will find the credentials by itself. For more information, go to https://cloud.google.com/docs/authentication/.

Service account key

If you are not running in a GCP environment, you will need to give the service account credentials to the exporter.

const { TraceExporter } = require('@google-cloud/opentelemetry-cloud-trace-exporter');

const exporter = new TraceExporter({
  /** option 1. provide a service account key json */
  keyFile: './service_account_key.json',
  keyFileName: './service_account_key.json',

  /** option 2. provide credentials directly */
  credentials: {
    client_email: string,
    private_key: string,
  },
});

Useful links

• For more information on OpenTelemetry, visit: https://opentelemetry.io/
• For more about OpenTelemetry JavaScript: https://github.com/open-telemetry/opentelemetry-js
• Learn more about Google Cloud Trace at https://cloud.google.com/trace