Logs Explorer Template

This is a template for a Logs Explorer web application. It is built with Next.js and Tinybird.

Use this template to bootstrap a user-facing logs explorer for any software project. Fork it and make it your own!

Tech Stack:

• Next.js
• Tinybird
• Clerk
• Vercel
• zod-bird
• Tailwind CSS
• Shadcn UI

Live Demo

• https://logs.tinybird.app
• Watch Demo Video

Quick Start

Deploy the Tinybird and Next.js to the cloud to get started quickly.

# select or create a new workspace
tb login

# deploy the template
tb --cloud deploy --template https://github.com/tinybirdco/logs-explorer-template/tree/main/tinybird

# copy the dashboard token
tb --cloud token copy read_pipes

Append the tinybird/fixtures/logs.ndjson file to the logs Data Source or stream some mock data.

Configure these Environment Variables in your Vercel project and you are ready to go:

NEXT_PUBLIC_TINYBIRD_API_KEY=<YOUR_TINYBIRD_READ_PIPES_TOKEN>
NEXT_PUBLIC_TINYBIRD_API_URL=<YOUR_TINYBIRD_REGION_HOST>

Get your read_pipes token and region host from the Tinybird dashboard. Never use an admin token here: NEXT_PUBLIC_ values are bundled into the client and ship to every browser.

Local Development

Get started by forking the GitHub repository and then customizing it to your needs.

Start Tinybird locally:

curl -LsSf https://tbrd.co/fwd | sh
cd tinybird
tb local start
tb login
tb dev
tb token copy read_pipes  # copy the read_pipes token

Configure the Next.js application:

cd dashboard/log-analyzer
cp .env.example .env

Edit the .env file with your Tinybird API key and other configuration.

NEXT_PUBLIC_TINYBIRD_API_KEY=<YOUR_TINYBIRD_LOCAL_READ_PIPES_TOKEN>
NEXT_PUBLIC_TINYBIRD_API_URL=http://localhost:7181

Start the Next.js application:

cd dashboard/log-analyzer
npm install
npm run dev

Open the application in your browser:

http://localhost:3000

Read the dashboard/log-analyzer/README.md file for more information on how to use the application and tinybird/README.md for more information on how to customize the template.

Authentication with Clerk (optional)

The template can use Clerk for sign-in. It does not isolate data between users or organizations: the logs Data Source has no tenant column, so every user, signed in or not, sees all logs in the workspace. Visitors who are not signed in use the read_pipes token from NEXT_PUBLIC_TINYBIRD_API_KEY.

Configure the .env file with your Clerk publishable key and secret.

CLERK_PUBLISHABLE_KEY=<YOUR_CLERK_PUBLISHABLE_KEY>
CLERK_SECRET_KEY=<YOUR_CLERK_SECRET_KEY>

Then set the Tinybird JWT secret and workspace ID in the .env file. These are server-only variables: never prefix them with NEXT_PUBLIC_.

TINYBIRD_JWT_SECRET=<YOUR_TINYBIRD_ADMIN_TOKEN>
TINYBIRD_WORKSPACE_ID=<YOUR_TINYBIRD_WORKSPACE_ID>

With these set, signed-in users get a short-lived JWT (15 minutes, 10 requests per second) that can read the same four endpoints as the read_pipes token. It does not restrict which logs they see. To add per-tenant isolation, add a tenant column to the logs Data Source, filter by it in every endpoint and pin it with fixed_params in the JWT.

// dashboard/log-analyzer/src/middleware.ts

const token = await new jose.SignJWT({
    workspace_id: process.env.TINYBIRD_WORKSPACE_ID,
    name: `frontend_jwt_user_${userId}`,
    exp: Math.floor(Date.now() / 1000) + (60 * 15), // 15 minute expiration
    iat: Math.floor(Date.now() / 1000),
    scopes: [
      {
        type: "PIPES:READ",
        resource: "log_analysis"
      },
      {
        type: "PIPES:READ",
        resource: "log_explorer"
      },
      {
        type: "PIPES:READ",
        resource: "generic_counter"
      },
      {
        type: "PIPES:READ",
        resource: "log_timeseries"
      }
    ],
    limits: {
      rps: 10
    }
  })
    .setProtectedHeader({ alg: 'HS256' })
    .sign(secret);

Read more about how to integrate Clerk and Tinybird JWT tokens in this guide.

Instrumenting your application

To instrument your application, just send JSON objects to the Tinybird Events API.

const data = {
    timestamp: new Date().toISOString(),
    level: 'info',
    service: 'my-app',
    message: 'This is a test message',
    request_id: '1234567890',
    environment: 'development',
    status_code: 200,
    response_time: 100,
    request_method: 'GET',
    request_path: '/',
    host: 'my-app.com',
    user_agent: req.headers.get('user-agent')
}
await fetch(
    `https://<YOUR_TINYBIRD_HOST>/v0/events?name=logs`,
    {
    method: 'POST',
    body: JSON.stringify(data),
    headers: { Authorization: `Bearer ${process.env.TINYBIRD_APPEND_TOKEN}` },
    }
)

The example above uses the logs Data Source and schema in this template but you can use your own Data Source and schema, append logs and build your own logs explorer application.

Check the examples folder for some examples of how to do this with different languages, services and schemas.

Building a log aggregator with Vector

Vector is a log aggregator that is used to collect, process, and store logs built by DataDog.

You can use Vector to collect logs from different sources and send them to a Tinybird Sink.

Check the examples/vector folder for an example of how to do this with Vector.

Deployment

Deploy the Tinybird project to the cloud:

cd tinybird
tb --cloud deploy

Once deployed copy your Tinybird cloud host and read_pipes token, deploy the Next.js application to Vercel and configure the environment variables.

Customizing the template

You can use the template as a starting point to build your own logs explorer application or embed components in your own application.

To customize the template, adapt the data sources and pipes in the tinybird project and the components in the Next.js application.

See how it's done in the Vercel Log Drains template and the Auth0 Log Streams template.

Contributing

Please open an issue or submit a pull request.

Support

Join the Tinybird Slack community to get help with your project.

License

MIT License

Copyright (c) 2025 Tinybird.co