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:
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.
Example Directory | Description |
---|
readme-demo | Example demo from the beginning of this README |
readme-demo-ts | Example demo from the beginning of this README, ported to TypeScript |
basic-tracing-example | Basic Tracing Example |
basic-tracing-example-ts | Basic Tracing Example in TypeScript |
basic-metrics-example | Basic Metrics Example |
otel-demo | Example that demonstrates OpenTelemetry traces that start at the Edge and nest into an operation at the backend. |
otel-http-proxy | A sample application designed to collect traces as an HTTPS log endpoint for a Fastly service, sending them to an OpenTelemetry collector. |
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.
Component | Package | Reason / Workaround |
---|
OTLPTraceExporter | @opentelemetry/exporter-trace-otlp-http | Relies on XmlHttpRequest and navigator.beacon , which are not available in Compute. Use OTLPTraceExporter from @fastly/compute-js-opentelemetry/exporter-trace-otlp-fastly-backend or @fastly/compute-js-opentelemetry/exporter-trace-otlp-fastly-logger instead. |
OTLPMetricExporter | @opentelemetry/exporter-metrics-otlp-http | Relies on XmlHttpRequest and navigator.beacon , which are not available in Compute. Use OTLPTraceExporter from @fastly/compute-js-opentelemetry/exporter-metrics-otlp-fastly-backend or @fastly/compute-js-opentelemetry/exporter-metrics-otlp-fastly-logger instead. |
ZoneContextManager | @opentelemetry/context-zone
@opentelemetry/context-zone-peer-dep | Relies on zone.js , which is incompatible with Compute. Use FastlyStackContextManager . |
AsyncHooksContextManager
AsyncLocalStorageContextManager | @opentelemetry/context-async-hooks | Relies on async_hooks , which is not available in Compute. Use FastlyStackContextManager . |
NodeSDK | @opentelemetry/sdk-node | This SDK is for Node, which is not compatible with Compute. Use FastlySDK . |
Instrumentations included in opentelemetry-js | @opentelemetry/instrumentation-*
@opentelemetry/auto-instrumentations-node
@opentelemetry/auto-instrumentations-web | These rely on other frameworks and modules that are not compatible with Compute. Use FastlyComputeJsInstrumentation and FastlyBackendFetchInstrumentation . |
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.