apitally 0.25.6 → 1.0.0-alpha.1

package/README.md

@@ -19,57 +19,39 @@
 </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)
 [![npm](https://img.shields.io/npm/v/apitally?logo=npm&color=%23cb0000)](https://www.npmjs.com/package/apitally)
 
-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.
+API monitoring, analytics and request logging for [AdonisJS](https://github.com/adonisjs/core), [Elysia](https://github.com/elysiajs/elysia), [Express](https://github.com/expressjs/express), [Fastify](https://github.com/fastify/fastify), [H3](https://github.com/h3js/h3), [Hapi](https://github.com/hapijs/hapi), [Hono](https://github.com/honojs/hono), [Koa](https://github.com/koajs/koa) and [NestJS](https://github.com/nestjs/nest), built on OpenTelemetry. One line of setup instruments your app and streams traces, logs and metrics to Apitally. No OpenTelemetry knowledge, infrastructure changes or dashboards are required.
 
-Learn more about Apitally on our 🌎 [website](https://apitally.io) or check out
-the 📚 [documentation](https://docs.apitally.io).
+Learn more about Apitally on our 🌎 [website](https://apitally.io) or check out the 📚 [documentation](https://docs.apitally.io).
 
 ## Key features
 
-### API analytics
-
-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.
-
-### Request logs
-
-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.
-
-### Error tracking
-
-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.
-
-### API monitoring & alerts
-
-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.
+- **API analytics**: Traffic, error and performance metrics for your API, each endpoint, and individual API consumers.
+- **Request logging**: Every request as a searchable log entry, with optional capture of headers and request/response bodies.
+- **Application logs**: Logs written via `console`, winston, pino, Hapi's `request.log()` or Nest's default `ConsoleLogger` are captured automatically and correlated with the request they belong to.
+- **Distributed tracing**: Requests are exported as OpenTelemetry spans, including spans from any other instrumentations you run.
+- **Error tracking**: Exceptions with stack traces for server errors, automatically linked to Sentry events if you use Sentry.
+- **Server metrics**: CPU, memory and uptime of your app's processes.
+- **Data privacy built in**: Sensitive headers and query parameters are masked by default, with configurable masking for anything else, plus sampling to control data volume.
 
 ## Supported frameworks
 
-| 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)     |
+| Framework | Supported versions | Setup guide |
+| --- | --- | --- |
+| [**AdonisJS**](https://github.com/adonisjs/core) | `>= 6.3`, `< 8` | [Link](https://docs.apitally.io/setup-guides/adonisjs) |
+| [**Elysia**](https://github.com/elysiajs/elysia) | `>= 1.1`, `< 2` | [Link](https://docs.apitally.io/setup-guides/elysia) |
+| [**Express**](https://github.com/expressjs/express) | `>= 4.18.2`, `< 6` | [Link](https://docs.apitally.io/setup-guides/express) |
+| [**Fastify**](https://github.com/fastify/fastify) | `>= 4.10.2`, `< 6` | [Link](https://docs.apitally.io/setup-guides/fastify) |
+| [**H3**](https://github.com/h3js/h3) \* | `>= 2.0.1-rc.26`, `< 3` | [Link](https://docs.apitally.io/setup-guides/h3) |
+| [**Hapi**](https://github.com/hapijs/hapi) | `21.x` | [Link](https://docs.apitally.io/setup-guides/hapi) |
+| [**Hono**](https://github.com/honojs/hono) \* | `>= 4.8.4`, `< 5` | [Link](https://docs.apitally.io/setup-guides/hono) |
+| [**Koa**](https://github.com/koajs/koa) | `2.x`, `3.x` | [Link](https://docs.apitally.io/setup-guides/koa) |
+| [**NestJS**](https://github.com/nestjs/nest) | `10.x`, `11.x` | [Link](https://docs.apitally.io/setup-guides/nestjs) |
 
 \* For Hono on Cloudflare Workers use our [Serverless SDK](https://github.com/apitally/apitally-js-serverless) instead.
 
@@ -77,146 +59,125 @@ Apitally also supports many other web frameworks in [Python](https://github.com/
 
 ## Getting started
 
-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.
+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, including your write token.
 
-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.
-
-### Express
-
-Install the SDK:
+Install the SDK. AdonisJS applications should use the Ace command in the next section instead.
 
 ```bash
 npm install apitally
 ```
 
-Then add the Apitally middleware to your application:
+Pass the write token via the `writeToken` option, or set the `APITALLY_WRITE_TOKEN` environment variable. 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.
 
-```javascript
-const express = require("express");
-const { useApitally } = require("apitally/express");
+### AdonisJS
 
-const app = express();
-app.use(express.json());
+Run the Ace add command from your application directory:
 
-useApitally(app, {
-  clientId: "your-client-id",
-  env: "dev", // or "prod" etc.
-});
+```bash
+node ace add apitally
 ```
 
-For further instructions, see our
-[setup guide for Express](https://docs.apitally.io/setup-guides/express).
-
-### Fastify
+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 report unhandled 5xx errors.
 
-Install the SDK with the `fastify-plugin` peer dependency:
+If Apitally is already installed, or to rerun setup, use:
 
 ```bash
-npm install apitally fastify-plugin
+node ace configure apitally
 ```
 
-Then register the Apitally plugin with your application:
+Request headers, request bodies, and response bodies are opt-in prompts during setup. Response headers are enabled by default. You can change these settings later in `config/apitally.ts`.
 
-```javascript
-import Fastify from "fastify";
-import { apitallyPlugin } from "apitally/fastify";
+The SDK-wide environment default is `dev`. `APITALLY_ENV` is deployment-specific, so set it appropriately for staging and production.
 
-const fastify = Fastify({ logger: true });
+For further instructions, see our [setup guide for AdonisJS](https://docs.apitally.io/setup-guides/adonisjs).
 
-await fastify.register(apitallyPlugin, {
-  clientId: "your-client-id",
-  env: "dev", // or "prod" etc.
-});
-```
+### Elysia
 
-_Note:_ If your project uses CommonJS you need to wrap your routes in a plugin, so Apitally can detect them.
+Register `apitallyPlugin()` immediately after creating the app, before routes or plugins that add routes:
 
-For further instructions, see our
-[setup guide for Fastify](https://docs.apitally.io/setup-guides/fastify).
+```javascript
+import { Elysia } from "elysia";
+import { apitallyPlugin } from "apitally/elysia";
 
-### NestJS
+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 }));
+```
 
-Install the SDK:
+For further instructions, see our [setup guide for Elysia](https://docs.apitally.io/setup-guides/elysia).
 
-```bash
-npm install apitally
-```
+### Express
 
-Then add the Apitally middleware to your application:
+Import `apitally/express/register` on the first line of your entry module, then call `useApitally(app)` anywhere after creating the app:
 
 ```javascript
-import { NestFactory } from "@nestjs/core";
-import { useApitally } from "apitally/nestjs";
-import { AppModule } from "./app.module";
+import "apitally/express/register"; // must be the first import
 
-async function bootstrap() {
-  const app = await NestFactory.create(AppModule);
+import express from "express";
+import { useApitally } from "apitally";
 
-  await useApitally(app, {
-    clientId: "your-client-id",
-    env: "dev", // or "prod" etc.
-  });
-
-  // ...
-}
+const app = express();
 
-bootstrap();
+useApitally(app, {
+  writeToken: "your-write-token", // or set APITALLY_WRITE_TOKEN
+  env: "dev", // optional, defaults to "dev"
+});
 ```
 
-For further instructions, see our
-[setup guide for NestJS](https://docs.apitally.io/setup-guides/nestjs).
+The register import ensures routes are captured no matter where they are registered — including routers assembled at module scope. It's one rule for every app shape: first line of your entry module.
 
-### AdonisJS
+For further instructions, see our [setup guide for Express](https://docs.apitally.io/setup-guides/express).
 
-Install the SDK:
+### Fastify
 
-```bash
-npm install apitally
-```
+Call `useApitally(app)` immediately after creating the app, before registering plugins and routes:
 
-Then use the following Ace command to configure Apitally in your AdonisJS application:
+```javascript
+import Fastify from "fastify";
+import { useApitally } from "apitally";
 
-```bash
-node ace configure apitally/adonisjs
-```
+const app = Fastify();
 
-For further instructions, see our
-[setup guide for AdonisJS](https://docs.apitally.io/setup-guides/adonisjs).
+useApitally(app, {
+  writeToken: "your-write-token", // or set APITALLY_WRITE_TOKEN
+  env: "dev", // optional, defaults to "dev"
+});
 
-### Hono
+// register plugins and routes below this point
+```
 
-Install the SDK:
+For further instructions, see our [setup guide for Fastify](https://docs.apitally.io/setup-guides/fastify).
 
-```bash
-npm install apitally
-```
+### NestJS
 
-Then add the Apitally middleware to your application:
+Call the synchronous `useApitally(app)` immediately after creating the Nest application, before `app.init()` or `app.listen()`:
 
 ```javascript
-import { Hono } from "hono";
-import { useApitally } from "apitally/hono";
+import { NestFactory } from "@nestjs/core";
+import { useApitally } from "apitally/nestjs";
+import { AppModule } from "./app.module.js";
 
-const app = new Hono();
+const app = await NestFactory.create(AppModule);
 
 useApitally(app, {
-  clientId: "your-client-id",
-  env: "dev", // or "prod" etc.
+  writeToken: "your-write-token", // or set APITALLY_WRITE_TOKEN
+  env: "dev", // optional, defaults to "dev"
 });
+
+await app.listen(3000);
 ```
 
-For further instructions, see our
-[setup guide for Hono](https://docs.apitally.io/setup-guides/hono).
+For further instructions, see our [setup guide for NestJS](https://docs.apitally.io/setup-guides/nestjs).
 
 ### H3
 
-Install the SDK:
-
-```bash
-npm install apitally
-```
-
-Then register the Apitally plugin with your application:
+Add `apitallyPlugin()` when constructing the root H3 app:
 
 ```javascript
 import { H3 } from "h3";
@@ -225,107 +186,153 @@ import { apitallyPlugin } from "apitally/h3";
 const app = new H3({
   plugins: [
     apitallyPlugin({
-      clientId: "your-client-id",
-      env: "dev", // or "prod" etc.
+      writeToken: "your-write-token", // or set APITALLY_WRITE_TOKEN
+      env: "dev", // optional, defaults to "dev"
     }),
   ],
 });
 ```
 
-For further instructions, see our
-[setup guide for H3](https://docs.apitally.io/setup-guides/h3).
+For further instructions, see our [setup guide for H3](https://docs.apitally.io/setup-guides/h3).
 
-### Elysia
+### Hapi
 
-Install the SDK:
+Register `apitallyPlugin()` before calling `server.initialize()` or `server.start()`:
 
-```bash
-npm install apitally
-```
+```javascript
+import Hapi from "@hapi/hapi";
+import { apitallyPlugin } from "apitally/hapi";
 
-Then add the Apitally plugin to your application:
+const server = Hapi.server({ port: 3000 });
 
-```javascript
-import { Elysia } from "elysia";
-import { apitallyPlugin } from "apitally/elysia";
+await server.register(
+  apitallyPlugin({
+    writeToken: "your-write-token", // or set APITALLY_WRITE_TOKEN
+    env: "dev", // optional, defaults to "dev"
+  }),
+);
 
-const app = new Elysia()
-  .use(
-    apitallyPlugin({
-      clientId: "your-client-id",
-      env: "dev", // or "prod" etc.
-    }),
-  )
-  .get("/", () => "hello");
+// register application plugins and routes below this point
+await server.start();
 ```
 
-For further instructions, see our
-[setup guide for Elysia](https://docs.apitally.io/setup-guides/elysia).
+For further instructions, see our [setup guide for Hapi](https://docs.apitally.io/setup-guides/hapi).
 
-### Koa
+### Hono
 
-Install the SDK:
+Call `useApitally(app)` immediately after creating the app — before registering middleware and routes, and before `app.fetch` is handed to the server:
 
-```bash
-npm install apitally
+```javascript
+import { Hono } from "hono";
+import { useApitally } from "apitally";
+
+const app = new Hono();
+
+useApitally(app, {
+  writeToken: "your-write-token", // or set APITALLY_WRITE_TOKEN
+  env: "dev", // optional, defaults to "dev"
+});
+
+// register middleware and routes below this point
 ```
 
-Then add the Apitally middleware to your application:
+For further instructions, see our [setup guide for Hono](https://docs.apitally.io/setup-guides/hono).
+
+### Koa
+
+Call `useApitally(app)` immediately after creating the app, before registering middleware and routes:
 
 ```javascript
 const Koa = require("koa");
-const { useApitally } = require("apitally/koa");
+const { useApitally } = require("apitally");
 
 const app = new Koa();
 
 useApitally(app, {
-  clientId: "your-client-id",
-  env: "dev", // or "prod" etc.
+  writeToken: "your-write-token", // or set APITALLY_WRITE_TOKEN
+  env: "dev", // optional, defaults to "dev"
 });
+
+// register middleware and routes below this point
 ```
 
-For further instructions, see our
-[setup guide for Koa](https://docs.apitally.io/setup-guides/koa).
+For further instructions, see our [setup guide for Koa](https://docs.apitally.io/setup-guides/koa).
 
-### Hapi
+## Trusted proxies
 
-Install the SDK:
+When your application runs behind a reverse proxy, configure the framework's trusted-proxy setting so Apitally can record the client IP for GeoIP. The SDK uses the client address resolved by Express, Fastify, Koa, AdonisJS, or the corresponding NestJS adapter. It does not trust forwarding headers directly.
 
-```bash
-npm install apitally
+## Using Sentry
+
+Sentry's Node.js SDK registers an OpenTelemetry tracer provider by default. If you use Sentry for error monitoring without performance tracing, let Apitally configure OpenTelemetry by disabling Sentry's setup:
+
+```javascript
+Sentry.init({
+  dsn: "your-sentry-dsn",
+  skipOpenTelemetrySetup: true,
+});
 ```
 
-Then register the Apitally plugin with your application:
+This keeps Sentry error reporting and Apitally's request logs and traces working together. If you use Sentry performance tracing, configure a shared OpenTelemetry provider and include `ApitallySpanProcessor` as described below.
+
+## Works with your existing OpenTelemetry setup
+
+If your app doesn't use OpenTelemetry, you don't need to know it's there — the SDK sets up a private, fully configured pipeline.
+
+If your app already registers its own tracer provider (e.g. via `NodeSDK`), Apitally never replaces it. Instead, add the `ApitallySpanProcessor` to your provider's span processors:
 
 ```javascript
-const Hapi = require("@hapi/hapi");
-const { apitallyPlugin } = require("apitally/hapi");
+import { NodeSDK } from "@opentelemetry/sdk-node";
+import { ApitallySpanProcessor } from "apitally";
 
-const init = async () => {
-  const server = Hapi.server({
-    port: 3000,
-    host: "localhost",
-  });
+const sdk = new NodeSDK({
+  spanProcessors: [new ApitallySpanProcessor()],
+  // ...your existing configuration
+});
+```
 
-  await server.register({
-    plugin: apitallyPlugin({
-      clientId: "your-client-id",
-      env: "dev", // or "prod" etc.
-    }),
-  });
-};
+Your existing exporters keep seeing everything they already see: Apitally adopts the spans your instrumentation produces instead of creating duplicates, and its meter and logger providers stay private, so nothing leaks into your own pipelines.
 
-init();
+When using Elysia's `@elysia/opentelemetry` plugin, register Apitally first so it adopts the OpenTelemetry SERVER span:
+
+```javascript
+import { opentelemetry } from "@elysia/opentelemetry";
+import { Elysia } from "elysia";
+import { apitallyPlugin } from "apitally/elysia";
+
+const app = new Elysia()
+  .use(apitallyPlugin(options))
+  .use(opentelemetry());
+```
+
+## Graceful shutdown
+
+Telemetry is exported in the background roughly every 15 seconds. After successful activation, Apitally installs `SIGTERM` and `SIGINT` listeners by default on supported POSIX main-thread processes. There is no opt-out, and the fixed five-second timeout is not configurable.
+
+On either signal, Apitally makes a non-destructive best-effort final drain of completed telemetry for up to five seconds. If another listener exists for that signal, that listener retains application lifecycle ownership. It must eventually terminate the process or allow it to drain naturally. If Apitally is the sole listener, it removes its listeners before draining and then restores the signal's original termination behavior. A repeated signal is therefore not delayed by another Apitally drain.
+
+Use the  `shutdown()` function for the coordinated full teardown path. Stop traffic and wait for in-flight work before awaiting it:
+
+```javascript
+import { shutdown } from "apitally";
+
+process.on("SIGTERM", () => {
+  server.close(async () => {
+    await shutdown();
+  });
+});
 ```
 
-For further instructions, see our
-[setup guide for Hapi](https://docs.apitally.io/setup-guides/hapi).
+## Runtime support
+
+- **Node.js** `>= 20.6`
+- **Bun** is supported for Elysia, H3 and Hono apps
+
+For edge and serverless runtimes like Cloudflare Workers, use our [Serverless SDK](https://github.com/apitally/apitally-js-serverless) instead.
 
 ## 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