vercel / otel

🚀 Vercel Otel

Note: This package is experimental. It doesn't follow semver yet. Minors can contain breaking changes.

@vercel/otel is a simple and easy-to-use package that sets up your trace provider and exporter.

💡 Use this package to quickly instrument your applications and get started with OpenTelemetry!

📦 Installation

npm install @vercel/otel

📚 Usage

import { registerOTel } from "@vercel/otel";
import { trace } from "@opentelemetry/api";

// Register the OpenTelemetry provider with an GRPC exporter
registerOTel("your-service-name");

// Now you can use the OpenTelemetry APIs
const span = trace.getTracer("your-component").startSpan("your-operation");

📖 API Reference

registerOTel(serviceName: string)

Registers the OpenTelemetry provider with an OTLP exporter using the given service name. This is all that is needed to trace your app on Vercel or any other platform exposing its own OpenTelemetry Collector.

• serviceName: The name of your service, used as the app name in many OpenTelemetry backends.

🧪 What exactly is this package doing

This package utilizes the exports API, enabling us to import the OpenTelemetry SDK in Node only. When you import registerOTel in a file intended for the edge, it returns an empty function because OpenTelemetry doesn't support the edge. However, if you import the same function in a file designed for Node, you'll receive a standard function that sets up the OpenTelemetry SDK correctly.

The OpenTelemetry SDK initialization itself is straightforward. For more details, please see the code.

📄 License

MIT

---

Made with 💖 by Vercel. Happy tracing! 📈

otel's Issues

Error with next build: Legacy octal escape is not permitted in strict mode

Description

When trying to use this package with latest Next.js, I get a build failure using next build

Steps to reproduce

1. pnpm create next-app my-app
2. Follow the instructions here: https://vercel.com/docs/concepts/observability/otel-overview/quickstart#-install-an-otel-integration-to-visualize-traces
3. pnpm run build

Expected:

Should build

Actual:

Throws Legacy octal escape is not permitted in strict mode.

./node_modules/.pnpm/[email protected]/node_modules/ansi-color/lib/ansi-color.js
Error: 
  × Legacy octal escape is not permitted in strict mode
    ╭─[/Users/tom.sherman/code/next-app-dir-tracing/node_modules/.pnpm/[email protected]/node_modules/ansi-color/lib/ansi-color.js:32:1]
 32 │   var color_attrs = color.split("+");
 33 │   var ansi_str = "";
 34 │   for(var i=0, attr; attr = color_attrs[i]; i++) {
 35 │     ansi_str += "\033[" + ANSI_CODES[attr] + "m";
    ·                  ──
 36 │   }
 37 │   ansi_str += str + "\033[" + ANSI_CODES["off"] + "m";
 38 │   return ansi_str;
    ╰────

  × Legacy octal escape is not permitted in strict mode
    ╭─[/Users/tom.sherman/code/next-app-dir-tracing/node_modules/.pnpm/[email protected]/node_modules/ansi-color/lib/ansi-color.js:34:1]
 34 │   for(var i=0, attr; attr = color_attrs[i]; i++) {
 35 │     ansi_str += "\033[" + ANSI_CODES[attr] + "m";
 36 │   }
 37 │   ansi_str += str + "\033[" + ANSI_CODES["off"] + "m";
    ·                      ──
 38 │   return ansi_str;
 39 │ };
    ╰────

Caused by:
    Syntax Error

Import trace for requested module:
./node_modules/.pnpm/[email protected]/node_modules/ansi-color/lib/ansi-color.js
./node_modules/.pnpm/[email protected]/node_modules/bufrw/annotated_buffer.js
./node_modules/.pnpm/[email protected]/node_modules/bufrw/interface.js
./node_modules/.pnpm/[email protected]/node_modules/bufrw/index.js
./node_modules/.pnpm/[email protected]/node_modules/thriftrw/index.js
./node_modules/.pnpm/[email protected]/node_modules/jaeger-client/dist/src/reporters/udp_sender.js
./node_modules/.pnpm/@[email protected]_@[email protected]/node_modules/@opentelemetry/exporter-jaeger/build/src/types.js
./node_modules/.pnpm/@[email protected]_@[email protected]/node_modules/@opentelemetry/exporter-jaeger/build/src/jaeger.js
./node_modules/.pnpm/@[email protected]_@[email protected]/node_modules/@opentelemetry/exporter-jaeger/build/src/index.js
./node_modules/.pnpm/@[email protected]_@[email protected]/node_modules/@opentelemetry/sdk-node/build/src/TracerProviderWithEnvExporter.js
./node_modules/.pnpm/@[email protected]_@[email protected]/node_modules/@opentelemetry/sdk-node/build/src/sdk.js
./node_modules/.pnpm/@[email protected]_@[email protected]/node_modules/@opentelemetry/sdk-node/build/src/index.js
./node_modules/.pnpm/@[email protected]/node_modules/@vercel/otel/dist/index.node.js
./src/OTEL-initializer.ts.ts
./src/fetcher.ts
./src/app/page.tsx

Reproduction repo

https://github.com/tom-sherman/next-app-dir-tracing

Additional info

vercel/otel version: 0.3.0
@opentelemetry/api: 1.4.1

Operating System:
      Platform: darwin
      Arch: arm64
      Version: Darwin Kernel Version 22.4.0: Mon Mar  6 20:59:28 PST 2023; root:xnu-8796.101.5~3/RELEASE_ARM64_T6000
    Binaries:
      Node: 18.13.0
      npm: 8.13.2
      Yarn: 1.22.19
      pnpm: 8.2.0
    Relevant packages:
      next: 13.4.4
      eslint-config-next: N/A
      react: 18.2.0
      react-dom: 18.2.0
      typescript: 5.0.4

Not recording fetch

It appears that fetch may not be instrumented. The docs appear to say it should work out of the box but a few spot checks doing fetch calls did not see any of them being reported. Happy to investigate in code if someone could point be in the right direction for where it’s implemented

Incorrect Peer Dependencies when Installing

There appears to be dependency issues with the project at this point.

Steps to Reproduce

1. Install a blank project with npx create-next-app and accept all the defaults.
2. Remove the npm lock file and run yarn install
3. Run yarn add @vercel/otel

Expected

The package installs with no warnings

Actual

I get several error messages for peer dependencies:

*[main][~/code/learning/otel-sandbox]$ yarn add @vercel/otel
yarn add v1.22.21
[1/4] 🔍  Resolving packages...
⠁ (node:26982) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative sinstead.
(Use `node --trace-deprecation ...` to show where the warning was created)
[2/4] 🚚  Fetching packages...
[3/4] 🔗  Linking dependencies...
warning "@vercel/otel > @opentelemetry/exporter-trace-otlp-grpc > @opentelemetry/[email protected]" has incorrect peer dependency "@opentelemetry/api@>=1.0.0 <1.5.0".
warning "@vercel/otel > @opentelemetry/[email protected]" has incorrect peer dependency "@opentelemetry/api@>=1.3.0 <1.5.0".
warning "@vercel/otel > @opentelemetry/sdk-node > @opentelemetry/[email protected]" has incorrect peer dependency "@opentelemetry/api@>=1.0.0 <1.5.0".
warning "@vercel/otel > @opentelemetry/exporter-trace-otlp-grpc > @opentelemetry/[email protected]" has incorrect peer dependency "@opentelemetry/api@>=1.0.0 <1.5.0".
warning "@vercel/otel > @opentelemetry/sdk-node > @opentelemetry/sdk-trace-node > @opentelemetry/[email protected]" has incorrect peer dependency "@opentelemetry/api@>=1.0.0 <1.5.0".
warning "@vercel/otel > @opentelemetry/exporter-trace-otlp-grpc > @opentelemetry/[email protected]" has incorrect peer dependency "@opentelemetry/api@>=1.3.0 <1.5.0".
warning "@vercel/otel > @opentelemetry/sdk-node > @opentelemetry/sdk-trace-node > @opentelemetry/[email protected]" has incorrect peer dependency "@opentelemetry/api@>=1.0.0 <1.5.0".
warning "@vercel/otel > @opentelemetry/sdk-node > @opentelemetry/sdk-trace-node > @opentelemetry/[email protected]" has incorrect peer dependency "@opentelemetry/api@>=1.0.0 <1.5.0".
warning "@vercel/otel > @opentelemetry/exporter-trace-otlp-grpc > @opentelemetry/[email protected]" has incorrect peer dependency "@opentelemetry/api@>=1.0.0 <1.5.0".
warning "@vercel/otel > @opentelemetry/sdk-node > @opentelemetry/[email protected]" has incorrect peer dependency "@opentelemetry/api@>=1.3.0 <1.5.0".
[4/4] 🔨  Building fresh packages...
success Saved lockfile.
success Saved 49 new dependencies.
info Direct dependencies
└─ @vercel/[email protected]
info All dependencies
├─ @grpc/[email protected]
├─ @opentelemetry/[email protected]
├─ @opentelemetry/[email protected]
├─ @opentelemetry/[email protected]
├─ @opentelemetry/[email protected]
├─ @opentelemetry/[email protected]
├─ @opentelemetry/[email protected]
├─ @opentelemetry/[email protected]
├─ @opentelemetry/[email protected]
├─ @opentelemetry/[email protected]
├─ @opentelemetry/[email protected]
├─ @opentelemetry/[email protected]
├─ @opentelemetry/[email protected]
├─ @opentelemetry/[email protected]
├─ @opentelemetry/[email protected]
├─ @protobufjs/[email protected]
├─ @protobufjs/[email protected]
├─ @protobufjs/[email protected]
├─ @protobufjs/[email protected]
├─ @protobufjs/[email protected]
├─ @protobufjs/[email protected]
├─ @protobufjs/[email protected]
├─ @protobufjs/[email protected]
├─ @protobufjs/[email protected]
├─ @vercel/[email protected]
├─ [email protected]
├─ [email protected]
├─ [email protected]
├─ [email protected]
├─ [email protected]
├─ [email protected]
├─ [email protected]
├─ [email protected]
├─ [email protected]
├─ [email protected]
├─ [email protected]
├─ [email protected]
├─ [email protected]
├─ [email protected]
├─ [email protected]
├─ [email protected]
├─ [email protected]
├─ [email protected]
├─ [email protected]
├─ [email protected]
├─ [email protected]
├─ [email protected]
├─ [email protected]
└─ [email protected]
✨  Done in 5.44s.
*

OTel support in the edge runtime

Hey people, I am the author of the new OTel library for Cloudflare Workers, which can now be done properly now that they have implemented AsyncLocalStorage.

Would you want to collaborate on making that work for the Vercel runtime? I would be happy to split up my package into core OTel and the Cloudflare Workers specific auto-instrumentation.

CommonJS import error

I'm trying to use the package in my project, but I'm getting an import error deep inside the @vercel/otel package, so there's nothing I can do about it.
I created the official nextjs example from the docs to ensure this wasn't a problem specific to my project.

$ npx create-next-app --example with-opentelemetry with-opentelemetry-app
$ npm run dev

> dev
> next

- ready started server on 0.0.0.0:3000, url: http://localhost:3000
- warn You have enabled experimental feature (instrumentationHook) in next.config.js.
- warn Experimental features are not covered by semver, and may cause unexpected or broken application behavior. Use at your own risk.

- event compiled client and server successfully in 129 ms (20 modules)
- wait compiling...
- wait compiling /instrumentation (client and server)...
- event compiled client and server successfully in 164 ms (62 modules)
file:///tmp/bla/with-opentelemetry-app/node_modules/@vercel/otel/dist/index.node.js:3
import { Resource } from "@opentelemetry/resources";
         ^^^^^^^^
SyntaxError: Named export 'Resource' not found. The requested module '@opentelemetry/resources' is a CommonJS module, which may not support all module.exports as named exports.
CommonJS modules can always be imported via the default export, for example using:

import pkg from '@opentelemetry/resources';
const { Resource } = pkg;

    at ModuleJob._instantiate (node:internal/modules/esm/module_job:124:21)
    at async ModuleJob.run (node:internal/modules/esm/module_job:190:5) {
  type: 'SyntaxError'
}

NodeJS version: 18.16.0
npm version: 9.5.1

Update

Apparently, the problem was that I followed these official instructions and there is missing the need to install @opentelemetry/api, which causes the error above.
Following other recipe solved the issue.

jaeger.thrift no such file or directory

I'm trying to get this set up with a NextJS app, however when I try to run the app I get the following error:

Error: An error occurred while loading instrumentation hook: ENOENT: no such file or directory, open '.next/server/jaeger-idl/thrift/jaeger.thrift'

I checked in the server folder and it is indeed not there. Did I miss a setup step?

Pass in additional resource attributes

At minimum it would be nice to set the environment. Even better if we could pass an entire attributes object.