apitally 0.25.8 → 1.0.0-beta.1

package/README.md

@@ -19,7 +19,7 @@
 </p>
 <br>
 
-# Apitally SDK for Node.js
+# Apitally SDK for JavaScript
 
 [![Tests](https://github.com/apitally/apitally-js/actions/workflows/tests.yaml/badge.svg?event=push)](https://github.com/apitally/apitally-js/actions)
 [![Codecov](https://codecov.io/gh/apitally/apitally-js/graph/badge.svg?token=j5jqlrL7Pd)](https://codecov.io/gh/apitally/apitally-js)
@@ -28,304 +28,354 @@
 Apitally is a simple API monitoring and analytics tool that makes it easy to understand API usage, monitor performance, and troubleshoot issues.
 Get started in minutes by just adding a few lines of code. No infrastructure changes required, no dashboards to build.
 
-Learn more about Apitally on our 🌎 [website](https://apitally.io) or check out
-the 📚 [documentation](https://docs.apitally.io).
+The SDK is an [OpenTelemetry](https://opentelemetry.io) distribution and works alongside an existing OpenTelemetry setup.
+
+Learn more about Apitally on our 🌎 [website](https://apitally.io) or check out the 📚 [documentation](https://docs.apitally.io).
+
+> [!IMPORTANT]
+> **Upgrading from 0.x?** Version 1.0 is a full rewrite with a new setup API. See the [migration guide](MIGRATION.md) for a full 0.x to 1.x mapping.
 
 ## Key features
 
-### API analytics
+- **API analytics**: Traffic, error and performance metrics for your API, each endpoint, and per API consumer. Drill down from metrics to individual API requests.
+- **Request logs and traces**: Every request as a searchable log entry, with optional capture of headers and request/response bodies. Requests are exported as OpenTelemetry spans, including spans from any other instrumentations you have.
+- **Application logs**: Logs written via `console` and other supported loggers are captured automatically and correlated with the requests they belong to.
+- **Error tracking**: Validation errors and exceptions with stack traces for server errors, automatically linked to Sentry events if you use Sentry.
+- **Server metrics**: CPU and memory usage of your app's processes.
+- **API monitoring & alerts**: Get notified if something isn't right using custom alerts, synthetic uptime checks and heartbeat monitoring. Alert notifications can be delivered via email, Slack and Microsoft Teams.
 
-Track traffic, error and performance metrics for your API, each endpoint and
-individual API consumers, allowing you to make informed, data-driven engineering
-and product decisions.
+## Supported frameworks
 
-### Request logs
+The SDK supports **Node.js** `>= 20.6` and **Bun** `>= 1.1.13`.
 
-Drill down from insights to individual API requests or use powerful search and filters to
-find specific requests. View correlated application logs and traces for a complete picture
-of each request, making troubleshooting faster and easier.
+| Framework | Supported versions | Setup guide |
+| --- | --- | --- |
+| [**AdonisJS**](https://github.com/adonisjs/core) | `>= 6.3`, `< 8` | [Link](https://docs.apitally.io/sdk-reference/javascript/v1/setup-guides/adonisjs) |
+| [**Elysia**](https://github.com/elysiajs/elysia) | `>= 1.1`, `< 2` | [Link](https://docs.apitally.io/sdk-reference/javascript/v1/setup-guides/elysia) |
+| [**Express**](https://github.com/expressjs/express) | `>= 4.18.2`, `< 6` | [Link](https://docs.apitally.io/sdk-reference/javascript/v1/setup-guides/express) |
+| [**Fastify**](https://github.com/fastify/fastify) | `>= 4.10.2`, `< 6` | [Link](https://docs.apitally.io/sdk-reference/javascript/v1/setup-guides/fastify) |
+| [**H3**](https://github.com/h3js/h3) | `>= 2.0.1-rc.26`, `< 3` | [Link](https://docs.apitally.io/sdk-reference/javascript/v1/setup-guides/h3) |
+| [**Hapi**](https://github.com/hapijs/hapi) | `21.x` | [Link](https://docs.apitally.io/sdk-reference/javascript/v1/setup-guides/hapi) |
+| [**Hono**](https://github.com/honojs/hono) \* | `>= 4.8.4`, `< 5` | [Link](https://docs.apitally.io/sdk-reference/javascript/v1/setup-guides/hono) |
+| [**Koa**](https://github.com/koajs/koa) | `2.x`, `3.x` | [Link](https://docs.apitally.io/sdk-reference/javascript/v1/setup-guides/koa) |
+| [**NestJS**](https://github.com/nestjs/nest) | `10.x`, `11.x`, `12.x` | [Link](https://docs.apitally.io/sdk-reference/javascript/v1/setup-guides/nestjs) |
 
-### Error tracking
+\* For Hono on Cloudflare Workers use our [Serverless SDK](https://github.com/apitally/apitally-js-serverless) instead.
 
-Understand which validation rules in your endpoints cause client errors. Capture
-error details and stack traces for 500 error responses, and have them linked to
-Sentry issues automatically.
+Apitally also supports many other web frameworks in [Python](https://github.com/apitally/apitally-py), [Go](https://github.com/apitally/apitally-go), [.NET](https://github.com/apitally/apitally-dotnet) and [Java](https://github.com/apitally/apitally-java) via our other SDKs.
 
-### API monitoring & alerts
+## Getting started
 
-Get notified immediately if something isn't right using custom alerts, synthetic
-uptime checks and heartbeat monitoring. Alert notifications can be delivered via
-email, Slack and Microsoft Teams.
+If you don't have an Apitally account yet, first [sign up here](https://app.apitally.io/?signup). Then create an app in the Apitally dashboard. You'll see detailed setup instructions with code snippets you can copy and paste. These also include your write token.
 
-## Supported frameworks
+To install the SDK as a dependency in your project run:
 
-| Framework                                           | Supported versions    | Setup guide                                            |
-| --------------------------------------------------- | --------------------- | ------------------------------------------------------ |
-| [**Express**](https://github.com/expressjs/express) | `4.x`, `5.x`          | [Link](https://docs.apitally.io/setup-guides/express)  |
-| [**Fastify**](https://github.com/fastify/fastify)   | `4.x`, `5.x`          | [Link](https://docs.apitally.io/setup-guides/fastify)  |
-| [**NestJS**](https://github.com/nestjs/nest)        | `9.x`, `10.x`, `11.x` | [Link](https://docs.apitally.io/setup-guides/nestjs)   |
-| [**AdonisJS**](https://github.com/adonisjs/core)    | `6.x`                 | [Link](https://docs.apitally.io/setup-guides/adonisjs) |
-| [**Hono**](https://github.com/honojs/hono) \*       | `4.x`                 | [Link](https://docs.apitally.io/setup-guides/hono)     |
-| [**H3**](https://github.com/h3js/h3)                | `2.x`                 | [Link](https://docs.apitally.io/setup-guides/h3)       |
-| [**Elysia**](https://github.com/elysiajs/elysia)    | `1.x`                 | [Link](https://docs.apitally.io/setup-guides/elysia)   |
-| [**Koa**](https://github.com/koajs/koa)             | `2.x`, `3.x`          | [Link](https://docs.apitally.io/setup-guides/koa)      |
-| [**Hapi**](https://github.com/hapijs/hapi)          | `21.x`                | [Link](https://docs.apitally.io/setup-guides/hapi)     |
+```bash
+npm install apitally
+```
 
-\* For Hono on Cloudflare Workers use our [Serverless SDK](https://github.com/apitally/apitally-js-serverless) instead.
+See the [SDK reference](https://docs.apitally.io/sdk-reference/javascript/v1/configuration) for all available configuration options, including how to mask sensitive data, capture request and response payloads, and more.
 
-Apitally also supports many other web frameworks in [Python](https://github.com/apitally/apitally-py), [Go](https://github.com/apitally/apitally-go), [.NET](https://github.com/apitally/apitally-dotnet) and [Java](https://github.com/apitally/apitally-java) via our other SDKs.
+### AdonisJS
 
-## Getting started
+Run the Ace add command from your application directory:
 
-If you don't have an Apitally account yet, first [sign up here](https://app.apitally.io/?signup). Then create an app in the Apitally dashboard. You'll see detailed setup instructions with code snippets you can copy and paste. These also include your client ID.
+```bash
+node ace add apitally
+```
 
-See the [SDK reference](https://docs.apitally.io/sdk-reference/javascript) for all available configuration options, including how to mask sensitive data, customize request logging, and more.
+The command installs and configures Apitally. It creates `config/apitally.ts`, adds the required environment declarations, registers the service provider and server middleware, and updates the conventional exception handler to capture validation and server errors.
 
-### Express
+If needed, you can change settings in `config/apitally.ts`.
 
-Install the SDK:
+For further instructions, see our [setup guide for AdonisJS](https://docs.apitally.io/sdk-reference/javascript/v1/setup-guides/adonisjs).
 
-```bash
-npm install apitally
+### Elysia
+
+Register `apitallyPlugin()` immediately after creating the app, before routes or plugins that add routes:
+
+```javascript
+import { Elysia } from "elysia";
+import { apitallyPlugin } from "apitally/elysia";
+
+const app = new Elysia()
+  .use(
+    apitallyPlugin({
+      writeToken: "your-write-token", // or set APITALLY_WRITE_TOKEN
+      env: "dev", // optional, defaults to "dev"
+    }),
+  )
+  // register plugins and routes below this point
+  .get("/items/:id", ({ params }) => ({ id: params.id }));
 ```
 
-Then add the Apitally middleware to your application:
+For further instructions, see our [setup guide for Elysia](https://docs.apitally.io/sdk-reference/javascript/v1/setup-guides/elysia).
+
+### Express
+
+Import `apitally/express/register` on the first line of your entry module, then call `useApitally(app)` anywhere after creating the app:
 
 ```javascript
-const express = require("express");
-const { useApitally } = require("apitally/express");
+import "apitally/express/register"; // must be the first import
+
+import express from "express";
+import { useApitally } from "apitally";
 
 const app = express();
-app.use(express.json());
 
 useApitally(app, {
-  clientId: "your-client-id",
+  writeToken: "your-write-token", // or set APITALLY_WRITE_TOKEN
   env: "dev", // or "prod" etc.
 });
 ```
 
-For further instructions, see our
-[setup guide for Express](https://docs.apitally.io/setup-guides/express).
+For further instructions, see our [setup guide for Express](https://docs.apitally.io/sdk-reference/javascript/v1/setup-guides/express).
 
 ### Fastify
 
-Install the SDK with the `fastify-plugin` peer dependency:
-
-```bash
-npm install apitally fastify-plugin
-```
-
-Then register the Apitally plugin with your application:
+Call `useApitally(app)` immediately after creating the app, before registering plugins and routes:
 
 ```javascript
 import Fastify from "fastify";
-import { apitallyPlugin } from "apitally/fastify";
+import { useApitally } from "apitally";
 
-const fastify = Fastify({ logger: true });
+const app = Fastify();
 
-await fastify.register(apitallyPlugin, {
-  clientId: "your-client-id",
+useApitally(app, {
+  writeToken: "your-write-token", // or set APITALLY_WRITE_TOKEN
   env: "dev", // or "prod" etc.
 });
-```
 
-_Note:_ If your project uses CommonJS you need to wrap your routes in a plugin, so Apitally can detect them.
+// register plugins and routes below this point
+```
 
-For further instructions, see our
-[setup guide for Fastify](https://docs.apitally.io/setup-guides/fastify).
+For further instructions, see our [setup guide for Fastify](https://docs.apitally.io/sdk-reference/javascript/v1/setup-guides/fastify).
 
 ### NestJS
 
-Install the SDK:
-
-```bash
-npm install apitally
-```
-
-Then add the Apitally middleware to your application:
+Call `useApitally(app)` immediately after creating the Nest application, before `app.init()` or `app.listen()`:
 
 ```javascript
 import { NestFactory } from "@nestjs/core";
 import { useApitally } from "apitally/nestjs";
-import { AppModule } from "./app.module";
+import { AppModule } from "./app.module.js";
 
-async function bootstrap() {
-  const app = await NestFactory.create(AppModule);
+const app = await NestFactory.create(AppModule);
 
-  await useApitally(app, {
-    clientId: "your-client-id",
-    env: "dev", // or "prod" etc.
-  });
-
-  // ...
-}
+useApitally(app, {
+  writeToken: "your-write-token", // or set APITALLY_WRITE_TOKEN
+  env: "dev", // or "prod" etc.
+});
 
-bootstrap();
+await app.listen(3000);
 ```
 
-For further instructions, see our
-[setup guide for NestJS](https://docs.apitally.io/setup-guides/nestjs).
+For further instructions, see our [setup guide for NestJS](https://docs.apitally.io/sdk-reference/javascript/v1/setup-guides/nestjs).
 
-### AdonisJS
+### H3
 
-Install the SDK:
+Add `apitallyPlugin()` when constructing the root H3 app:
 
-```bash
-npm install apitally
+```javascript
+import { H3 } from "h3";
+import { apitallyPlugin } from "apitally/h3";
+
+const app = new H3({
+  plugins: [
+    apitallyPlugin({
+      writeToken: "your-write-token", // or set APITALLY_WRITE_TOKEN
+      env: "dev", // or "prod" etc.
+    }),
+  ],
+});
 ```
 
-Then use the following Ace command to configure Apitally in your AdonisJS application:
+For further instructions, see our [setup guide for H3](https://docs.apitally.io/sdk-reference/javascript/v1/setup-guides/h3).
 
-```bash
-node ace configure apitally/adonisjs
-```
+### Hapi
 
-For further instructions, see our
-[setup guide for AdonisJS](https://docs.apitally.io/setup-guides/adonisjs).
+Register `apitallyPlugin()` before calling `server.initialize()` or `server.start()`:
 
-### Hono
+```javascript
+import Hapi from "@hapi/hapi";
+import { apitallyPlugin } from "apitally/hapi";
 
-Install the SDK:
+const server = Hapi.server({ port: 3000 });
 
-```bash
-npm install apitally
+await server.register(
+  apitallyPlugin({
+    writeToken: "your-write-token", // or set APITALLY_WRITE_TOKEN
+    env: "dev", // or "prod" etc.
+  }),
+);
+
+// register application plugins and routes below this point
+await server.start();
 ```
 
-Then add the Apitally middleware to your application:
+For further instructions, see our [setup guide for Hapi](https://docs.apitally.io/sdk-reference/javascript/v1/setup-guides/hapi).
+
+### Hono
+
+Call `useApitally(app)` immediately after creating the app, before registering middleware and routes:
 
 ```javascript
 import { Hono } from "hono";
-import { useApitally } from "apitally/hono";
+import { useApitally } from "apitally";
 
 const app = new Hono();
 
 useApitally(app, {
-  clientId: "your-client-id",
+  writeToken: "your-write-token", // or set APITALLY_WRITE_TOKEN
   env: "dev", // or "prod" etc.
 });
+
+// register middleware and routes below this point
 ```
 
-For further instructions, see our
-[setup guide for Hono](https://docs.apitally.io/setup-guides/hono).
+For further instructions, see our [setup guide for Hono](https://docs.apitally.io/sdk-reference/javascript/v1/setup-guides/hono).
 
-### H3
+### Koa
 
-Install the SDK:
+Call `useApitally(app)` immediately after creating the app, before registering middleware and routes:
 
-```bash
-npm install apitally
+```javascript
+const Koa = require("koa");
+const { useApitally } = require("apitally");
+
+const app = new Koa();
+
+useApitally(app, {
+  writeToken: "your-write-token", // or set APITALLY_WRITE_TOKEN
+  env: "dev", // or "prod" etc.
+});
+
+// register middleware and routes below this point
 ```
 
-Then register the Apitally plugin with your application:
+For further instructions, see our [setup guide for Koa](https://docs.apitally.io/sdk-reference/javascript/v1/setup-guides/koa).
 
-```javascript
-import { H3 } from "h3";
-import { apitallyPlugin } from "apitally/h3";
+## Configuration
 
-const app = new H3({
-  plugins: [
-    apitallyPlugin({
-      clientId: "your-client-id",
-      env: "dev", // or "prod" etc.
-    }),
-  ],
+The write token and environment can also be provided via the `APITALLY_WRITE_TOKEN` and `APITALLY_ENV` environment variables instead of the `writeToken` and `env` options. The environment defaults to `dev`.
+
+By default, Apitally captures response headers but not request headers or request and response bodies. You can opt in with options:
+
+```javascript
+useApitally(app, {
+  writeToken: "your-write-token",
+  env: "dev",
+  captureRequestHeaders: true,
+  captureRequestBody: true,
+  captureResponseBody: true,
 });
 ```
 
-For further instructions, see our
-[setup guide for H3](https://docs.apitally.io/setup-guides/h3).
+Sensitive values in query parameters, headers, and body fields are masked automatically based on built-in patterns, and you can add your own via the `maskQueryParams`, `maskHeaders`, and `maskBodyFields` options.
 
-### Elysia
+On high-traffic applications you can capture logs and traces for only a fraction of requests by setting `sampleRate` (e.g. `0.1` for 10%), or decide per request with the `sampleOnRequest` and `sampleOnResponse` callbacks. Metrics always count every request, regardless of sampling.
 
-Install the SDK:
+Application logs written via `console` and other supported loggers are captured and correlated with requests by default. Use `maskLogRecord` to transform or drop Apitally's captured copy, or opt out with `captureLogs: false`.
 
-```bash
-npm install apitally
-```
+See the [SDK reference](https://docs.apitally.io/sdk-reference/javascript/v1/configuration) for all configuration options.
 
-Then add the Apitally plugin to your application:
+## Identifying consumers and more
+
+The top-level `apitally` package provides functions you can call from anywhere in your request handling code:
 
 ```javascript
-import { Elysia } from "elysia";
-import { apitallyPlugin } from "apitally/elysia";
+import { setConsumer, setRequestAttribute, captureException } from "apitally";
 
-const app = new Elysia()
-  .use(
-    apitallyPlugin({
-      clientId: "your-client-id",
-      env: "dev", // or "prod" etc.
-    }),
-  )
-  .get("/", () => "hello");
+// Associate the current request with an API consumer
+setConsumer({ identifier: user.identifier, name: user.name, group: user.group });
+
+// Attach a custom attribute to the current request
+setRequestAttribute("tenant", tenantId);
+
+// Capture a handled exception for the current request
+captureException(error);
 ```
 
-For further instructions, see our
-[setup guide for Elysia](https://docs.apitally.io/setup-guides/elysia).
+`setConsumer()` also accepts an identifier string, for example `setConsumer(user.identifier)`.
 
-### Koa
+For further details, check out our [documentation](https://docs.apitally.io).
 
-Install the SDK:
+## Existing OpenTelemetry setup
 
-```bash
-npm install apitally
-```
+If your app doesn't already use OpenTelemetry, you don't need to know it's there. The Apitally SDK configures OpenTelemetry automatically.
 
-Then add the Apitally middleware to your application:
+If your app already registers its own tracer provider (e.g. via `NodeSDK`), Apitally does not replace it. Instead, you need to add the `ApitallySpanProcessor` to your provider's span processors:
 
 ```javascript
-const Koa = require("koa");
-const { useApitally } = require("apitally/koa");
+import { NodeSDK } from "@opentelemetry/sdk-node";
+import { ApitallySpanProcessor } from "apitally";
 
-const app = new Koa();
-
-useApitally(app, {
-  clientId: "your-client-id",
-  env: "dev", // or "prod" etc.
+const sdk = new NodeSDK({
+  spanProcessors: [new ApitallySpanProcessor()],
+  // ...your existing configuration
 });
 ```
 
-For further instructions, see our
-[setup guide for Koa](https://docs.apitally.io/setup-guides/koa).
+Your tracer provider's sampling settings also affect Apitally. Requests excluded by the sampler will not have request logs or traces in Apitally. Metrics still include all requests, regardless of sampling.
 
-### Hapi
+### Sentry
 
-Install the SDK:
+Sentry's Node.js SDK configures OpenTelemetry automatically. To use Apitally alongside Sentry, add `ApitallySpanProcessor` to Sentry's configuration and call `Sentry.init()` before `useApitally()`:
 
-```bash
-npm install apitally
+```javascript
+import * as Sentry from "@sentry/node";
+import { ApitallySpanProcessor } from "apitally";
+
+Sentry.init({
+  dsn: "your-sentry-dsn",
+  // Enable tracing
+  tracesSampleRate: 1.0,
+  // Add Apitally's span processor
+  openTelemetrySpanProcessors: [new ApitallySpanProcessor()],
+  // Optional: send only errors to Sentry
+  beforeSendTransaction: () => null,
+});
 ```
 
-Then register the Apitally plugin with your application:
+Apitally uses the spans recorded by Sentry, so tracing must be enabled in Sentry. Requests excluded by Sentry's sampler will also be missing from Apitally's request logs and traces.
+
+Returning `null` from `beforeSendTransaction` prevents traces from being sent to Sentry without affecting Apitally's request logs and traces.
+
+### Elysia's OpenTelemetry plugin
+
+When using Elysia's `@elysia/opentelemetry` plugin, register Apitally first so it adopts the OpenTelemetry SERVER span:
 
 ```javascript
-const Hapi = require("@hapi/hapi");
-const { apitallyPlugin } = require("apitally/hapi");
-
-const init = async () => {
-  const server = Hapi.server({
-    port: 3000,
-    host: "localhost",
-  });
-
-  await server.register({
-    plugin: apitallyPlugin({
-      clientId: "your-client-id",
-      env: "dev", // or "prod" etc.
-    }),
-  });
-};
+import { opentelemetry } from "@elysia/opentelemetry";
+import { Elysia } from "elysia";
+import { apitallyPlugin } from "apitally/elysia";
 
-init();
+const app = new Elysia()
+  .use(apitallyPlugin(options))
+  .use(opentelemetry());
 ```
 
-For further instructions, see our
-[setup guide for Hapi](https://docs.apitally.io/setup-guides/hapi).
+## Trusted proxies
+
+If your application runs behind a reverse proxy or load balancer, configure trusted proxies in your framework so Apitally can record the real client IP for GeoIP. Apitally uses the client IP reported by your framework. It does not read forwarding headers itself to determine the client IP.
+
+## Graceful shutdown
+
+Apitally sends telemetry in batches and automatically attempts a final export during normal process shutdown.
+
+If your code calls `process.exit()`, await `shutdown()` first to give Apitally time to send buffered telemetry. Close your server and let any remaining requests finish before doing this:
+
+```javascript
+import { shutdown } from "apitally";
+
+// After the server has closed and requests have finished:
+await shutdown();
+process.exit(0);
+```
 
 ## Getting help
 
-If you need help please
-[create a new discussion](https://github.com/orgs/apitally/discussions/categories/q-a)
-on GitHub or email us at [support@apitally.io](mailto:support@apitally.io). We'll get back to you as soon as possible.
+If you need help please [create a new discussion](https://github.com/orgs/apitally/discussions/categories/q-a) on GitHub or email us at [support@apitally.io](mailto:support@apitally.io). We'll get back to you as soon as possible.
 
 ## License