> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apitally.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Setup guide for Hono on Cloudflare Workers

> Just a few simple steps to get started with Apitally.

export const framework_0 = "Hono (Cloudflare Workers)"

This page guides you through the steps of configuring your [Hono](https://hono.dev) application running on [Cloudflare Workers](https://developers.cloudflare.com/workers/) to work with Apitally.
If you don't have an account yet, now would be a good time to [sign up](https://app.apitally.io/?signup).

Once you're done with this guide, you will be able to:

* Get detailed metrics on API usage, errors, and performance
* Track API adoption and usage by individual consumers
* Log individual API requests, responses, and correlated application logs
* See what's causing slow API requests with traces
* Monitor uptime and set up custom alerts

## Create app

To get started, create a new app in the [Apitally dashboard](https://app.apitally.io/apps) and select {framework_0} as your framework.

<img src="https://assets.apitally.io/docs/2025-12-08/create-app.webp" alt="Create app" className="rounded-xl" />

You can also configure the environments (e.g. `prod` and `dev`) for your app, or simply accept the defaults.

After submitting, you will see tailored setup instructions for your app. These include code snippets you can copy and paste into your project.

<Note>
  The **client ID** provided in the setup instructions uniquely identifies your app for the purpose of data ingestion only. It does not grant any kind of read access to your data.
</Note>

## Create Logpush job

Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/) and navigate to *Analytics & Logs > Logpush*. Create a [Logpush](https://developers.cloudflare.com/workers/observability/logs/logpush/) job with the following settings:

| Setting                      | Value                                                                                            |
| ---------------------------- | ------------------------------------------------------------------------------------------------ |
| Destination                  | HTTP destination                                                                                 |
| HTTP endpoint                | `https://hub.apitally.io/v2/{client-id}/{env}/logpush`                                           |
| Dataset                      | Workers trace events                                                                             |
| If logs match...             | Filtered logs: <br /> EventType equals `fetch` and <br /> ScriptName equals `{your-worker-name}` |
| Send the following fields... | General: <br /> Event, EventTimestampMs, Logs                                                    |

In the HTTP endpoint, replace `{client-id}` with your app's client ID and `{env}` with the environment (e.g. `prod` or `dev`). In the filter criteria, replace `{your-worker-name}` with the name of your Worker, as specified in your Wrangler config.

## Add middleware

Next, install the [Apitally Serverless SDK](/sdk-reference/javascript-serverless/overview) in your project.

<CodeGroup>
  ```shell npm theme={null}
  npm install @apitally/serverless
  ```

  ```shell yarn theme={null}
  yarn add @apitally/serverless
  ```
</CodeGroup>

Add the Apitally middleware to your Hono application using the `useApitally` function.

```javascript theme={null}
import { Hono } from "hono";
import { useApitally } from "@apitally/serverless/hono";

const app = new Hono();

useApitally(app);

// Ensure route handlers are registered after useApitally()
```

<div>
  <Note>
    Add the Apitally middleware before any other middleware to ensure it wraps the entire stack.
  </Note>
</div>

## Configure Worker

Enable [Workers Logs](https://developers.cloudflare.com/workers/observability/logs/workers-logs/) and [Logpush](https://developers.cloudflare.com/workers/observability/logs/logpush/) in your Wrangler configuration file.

<CodeGroup>
  ```toml wrangler.toml theme={null}
  logpush = true

  [observability]
  enabled = true
  head_sampling_rate = 1

  [observability.logs]
  invocation_logs = true
  ```

  ```json wrangler.json theme={null}
  {
    "logpush": true,
    "observability": {
      "enabled": true,
      "head_sampling_rate": 1,
      "logs": {
        "invocation_logs": true
      }
    }
  }
  ```
</CodeGroup>

Then, deploy your application to Cloudflare Workers.

```shell theme={null}
wrangler deploy
```

<Check>
  At this point the basic setup for your application is complete and you will start seeing data in the Apitally dashboard after the first request is handled.
</Check>

<Note>
  It can take 2-3 minutes for requests to show up in Apitally due to how Cloudflare Logpush batches log data before sending it.

  Also note that Cloudflare Logpush doesn't include requests from local development environments, so you won't see them in the Apitally dashboard.
</Note>

## Identify consumers

To analyze and filter API traffic by consumers, you can associate requests with consumer identifiers in your application.

In most cases, use the authenticated identity to identify the consumer.
The identifier should be a string, such as a username, email address, or any other unique identifier.

Optionally, you can also provide a display name and group for each consumer.

Use the `setConsumer` function to associate requests with consumers, for example in a middleware.

<CodeGroup>
  ```javascript Identifier only theme={null}
  import { setConsumer } from "@apitally/serverless/hono";

  app.use(async (c, next) => {
    const consumerIdentifier = c.get("jwtPayload")?.sub;
    setConsumer(c, consumerIdentifier);
    await next();
  });
  ```

  ```javascript With name and group theme={null}
  import { setConsumer } from "@apitally/serverless/hono";

  app.use(async (c, next) => {
    const payload = c.get("jwtPayload");
    if (payload) {
      setConsumer(c, {
        identifier: payload.sub,
        name: payload.name, // optional
        group: payload.group, // optional
      });
    }
    await next();
  });
  ```
</CodeGroup>

<Check>
  The *Consumers* dashboard now shows all consumers that have made requests to your application. You can also filter other dashboards by consumer.
</Check>

## Configure request logging

With the serverless SDK, request logging is enabled by default, however request headers and request/response bodies are not included unless explicitly enabled.

The SDK automatically applies [default masking rules](/data-privacy#data-masking) for common sensitive headers and request/response body fields. You can configure additional masking rules and exclude certain requests from logging.

<CodeGroup>
  ```javascript Basic example theme={null}
  import { Hono } from "hono";
  import { useApitally } from "@apitally/serverless/hono";

  const app = new Hono();

  useApitally(app, {
    logRequestHeaders: true,
    logRequestBody: true,
    logResponseBody: true,
  });
  ```

  ```javascript Advanced example theme={null}
  import { Hono } from "hono";
  import { useApitally } from "@apitally/serverless/hono";

  const app = new Hono();

  useApitally(app, {
    logRequestHeaders: true,
    logRequestBody: true,
    logResponseHeaders: true,
    logResponseBody: true,
    // Mask headers using regex
    maskHeaders: [/^X-Sensitive-Header$/i],
    // Mask request/response body fields using regex
    maskBodyFields: [/^sensitive_field$/i],
    // Exclude paths from request logging using regex
    excludePaths: [/\/health$/, /\/metrics$/],
  });
  ```
</CodeGroup>

<Check>
  The *Request logs* dashboard now shows individual requests handled by your application, including headers and payloads, if enabled. You can filter, search, and inspect them in detail.
</Check>