Getting started

Follow these steps to send logs from your app to Logger. No prior knowledge assumed—account, project, key, install, then log.

Prerequisites

Node.js 18+ (or a browser build if you use the SDK in the browser), and a Logger account. For Go: Go 1.18+ and the same API key; no SDK install required.

1. Create an account

Sign up at the dashboard. Confirm your email if required, then sign in.

2. Create a project

In the dashboard, go to API Keys and click Create project. Enter a name (e.g. "My App"). The slug is optional and auto-generated from the name if you leave it empty.

3. Create an API key

Dashboard → API Keys → Create API key. Select your project, choose environment (Live or Sandbox), add an optional label, then Create. Copy the key—it is shown only once.

4. Install the SDK

npm install @logship/logger

Alternative: Don't want to install an NPM package? Use our SDK-less ingestion API via simple HTTP requests (cURL, fetch, etc.). See API reference for examples.

5. Set environment variables

Your server or app needs:

• LOGGER_API_KEY – Your API key (required). Keep this secret.
• LOGGER_API_URL – Optional. Default is our hosted ingestion URL. To use a custom endpoint (yours or local), set LOGGER_API_URL or pass endpoint in init({ apiKey, endpoint: 'https://...' }).

Example .env (from our test-backend example):

# Copy to .env and set your API key (from dashboard → API Keys).
# .env is gitignored; never commit the key.
# SDK uses hosted Logship URL by default; set LOGGER_API_URL only for local dev.

LOGGER_API_KEY=lb_sb_xxxx
# LOGGER_API_URL=http://localhost:3000   # only for local / self-hosted
PORT=4000

6. Initialize and log

Create a logger and send events. This snippet matches the test-backend example we ship in the repo (examples/test-backend):

import 'dotenv/config';
import { init } from '@logship/logger';

const API_URL = process.env.LOGGER_API_URL || 'http://localhost:3000';
const API_KEY = process.env.LOGGER_API_KEY?.trim();
if (!API_KEY) {
  console.error('Set LOGGER_API_KEY (from dashboard API Keys).');
  process.exit(1);
}

const logger = init({
  apiKey: API_KEY,
  endpoint: API_URL,
  minLevel: 'debug',
  defaultMetadata: { service: 'my-service', version: '0.1.0' },
});

logger.info('Server starting', { port: 4000, apiUrl: API_URL });

// In your request handler:
logger.info('Request received', { path: '/ping', method: 'GET' });

Events are buffered in memory and sent in batches. Use logger.flush() to send immediately (e.g. before process exit).

6b. Full server example (from test-backend)

Below is the complete pattern from examples/test-backend: request handler (all routes), server setup, and graceful shutdown so buffered logs are flushed before exit. Copy each block for a smooth experience.

Request handler (/ping, /log-sample, /flush)

async function handleRequest(url: string, method: string): Promise<{ status: number; body: string }> {
  if (url === '/ping' || url === '/') {
    logger.info('Request received', { path: url, method });
    return { status: 200, body: 'OK. Check dashboard Logs for this event.\n' };
  }
  if (url === '/log-sample') {
    logger.debug('Debug sample');
    logger.info('Info sample', { foo: 'bar' });
    logger.warn('Warn sample');
    logger.error('Error sample', { code: 500 });
    await logger.flush();
    return { status: 200, body: 'Logged 4 events. Flushed. Check dashboard.\n' };
  }
  if (url === '/flush') {
    await logger.flush();
    return { status: 200, body: 'Buffer flushed.\n' };
  }
  return { status: 404, body: 'Not found. Try /ping or /log-sample or /flush\n' };
}

Server setup (createServer + listen)

async function main(): Promise<void> {
  const server = http.createServer(async (req, res) => {
    const url = req.url ?? '/';
    const method = req.method ?? 'GET';
    const { status, body } = await handleRequest(url, method);
    res.writeHead(status, { 'Content-Type': 'text/plain' });
    res.end(body);
  });

  server.listen(PORT, () => {
    console.log(`Server: http://localhost:${PORT}`);
    console.log('  /ping      – send one log, respond OK');
    console.log('  /log-sample – debug/info/warn/error, then flush');
    console.log('  /flush     – flush buffer');
  });

  // Add shutdown handler below (so buffer is flushed on Ctrl+C / SIGTERM).
}

Graceful shutdown (flush before exit)

Add this inside main() after server.listen(...) so buffered logs are sent before the process exits.

const shutdown = (): void => {
  logger.info('Shutting down');
  logger.flush().then(() => {
    server.close();
    process.exit(0);
  });
};
process.on('SIGINT', shutdown);
process.on('SIGTERM', shutdown);

On Ctrl+C or SIGTERM, the logger flushes the buffer before the process exits so no logs are lost. At the end of your file, run main().catch((err) => { console.error(err); process.exit(1); });.

7. View logs

In the dashboard, go to Logs, select your project and environment. Logs appear after the SDK flushes (on interval or when the buffer is full). Until then, pending events are still in the buffer.

8. Try the test-backend (reference)

We provide a minimal runnable backend in examples/test-backend that uses @logship/logger exactly as above. Use it to verify your API key and see logs in the dashboard.

Prerequisites: API running (e.g. docker compose up or apps/api on port 3000).

cd examples/test-backend
npm install
cp .env.example .env
# Edit .env: set LOGGER_API_KEY=lb_sb_xxxx (from dashboard)
npm run dev

Then open http://localhost:4000/ping or http://localhost:4000/log-sample; check Dashboard → Logs for the events.

9. Optional: configure

You can set minLevel, defaultMetadata, env, and more. See the SDK reference for the full configuration table and examples.

Other languages (Go)

Use the same ingestion API from Go—no SDK required. POST /v1/logs with Authorization: Bearer <api_key> and body {"events":[...]}. See the Go client docs for a minimal example and links to the repo.