OpenTelemetry for JavaScript on Fastly Compute

An implementation of the OpenTelemetry JavaScript API for Fastly Compute.

Generate traces like this one to follow activity and time in your Compute applications:

index.js:

/// <reference types="@fastly/js-compute" />

import './telemetry.js'
import { context, trace } from "@opentelemetry/api";

addEventListener("fetch", (event) => event.respondWith(handleRequest(event)));
async function handleRequest(event) {
  const tracer = trace.getTracerProvider()
    .getTracer('my-tracer');

  const mySpan = tracer.startSpan('my-task');
  context.with(trace.setSpan(context.active(), mySpan), () => {
    doTask();
  });
  mySpan.end();

  return new Response('OK', {
    status: 200,
    headers: new Headers({"Content-Type": "text/plain"}),
  });
}

telemetry.js:

import { context, trace } from "@opentelemetry/api";
import { Resource } from "@opentelemetry/resources";
import { SEMRESATTRS_SERVICE_NAME } from "@opentelemetry/semantic-conventions";

import { FastlySDK } from "@fastly/compute-js-opentelemetry/sdk-fastly";
import { OTLPTraceExporter } from "@fastly/compute-js-opentelemetry/exporter-trace-otlp-fastly-backend";
import { getComputeJsAutoInstrumentations } from "@fastly/compute-js-opentelemetry/auto-instrumentations-compute-js";

const sdk = new FastlySDK({
  traceExporter: new OTLPTraceExporter({ backend: 'otlp-collector' }),
  instrumentations: [ getComputeJsAutoInstrumentations(), ],
  resource: new Resource({ [SEMRESATTRS_SERVICE_NAME]: 'readme-demo', }),
});
await sdk.start();

This implementation extends the standard interfaces and objects provided by the OpenTelemetry JavaScript API and SDK, adapting them for use on the Fastly Compute platform.

New!

As of v0.3.0, @fastly/compute-js-opentelemetry no longer requires Webpack.

Additionally, if you're using the FastlySDK module, you will need @fastly/js-compute v3.11.0 or newer and enable Top Level Await. Find where you call the binary js-compute-runtime and add the flag like so js-compute-runtime --experimental-enable-top-level-await (This is usually in either package.json or fastly.toml).

Look at the demos included in this package for working examples.

Modules

Whereas opentelemetry-js would separate each concern into its own npm package, we provide our components as a single package with multiple exports.

Examples

See the examples in the /examples directory.

Use with TypeScript

This library is designed to work with both JavaScript and TypeScript applications written for Fastly Compute.

Check out readme-demo-ts and basic-tracing-example-ts in the examples directory for working sample programs using TypeScript.

Notes

Environment Variables

OpenTelemetry defines a well-documented set of environment variables that are designed to allow you to configure defaults for its libraries. However, JavaScript applications built to run on Fastly's Compute platform perform their upfront initialization at build time ("build-time initialization") rather than during each invocation (that's how they start up so fast). This means that the platform cannot provide a way to read from the environment during build-time initialization, when most OpenTelemetry libraries are initializing.

Therefore, when using this library, the getEnv() function will always return the default values defined by OpenTelemetry. Any changes you require to these defaults need to be made programmatically.

Compatibility

Some opentelemetry-js modules are not currently compatible with Fastly Compute. The table below is a non-comprehensive list of such components.

Issues

If you encounter any non-security-related bug or unexpected behavior, please file an issue using the bug report template.

Security issues

Please see our SECURITY.md for guidance on reporting security-related issues.

License

MIT.