Blyp Docs

Configuration

Blyp configuration comes from two places:

Runtime overrides are merged on top of the loaded config.

Supported config files

Blyp loads the first matching config file from:

Executable config files are loaded through jiti.

Example blyp.config.ts

export default {
  "pretty": true,
  "level": "info",
  "destination": "database",
  "redact": {
    "paths": ["user.ssn", "payment.**.raw"]
  },
  "file": {
    "enabled": true,
    "format": "ndjson",
    "rotation": {
      "enabled": true,
      "maxSizeBytes": 10485760,
      "maxArchives": 5,
      "compress": true
    }
  },
  "database": {
    "dialect": "postgres",
    "delivery": {
      "strategy": "immediate",
      "batchSize": 1,
      "flushIntervalMs": 250,
      "maxQueueSize": 1000,
      "overflowStrategy": "drop-oldest",
      "flushTimeoutMs": 5000,
      "retry": {
        "maxRetries": 1,
        "backoffMs": 100
      }
    }
  },
  "clientLogging": {
    "enabled": true,
    "path": "/inngest"
  },
  "connectors": {
    "delivery": {
      "enabled": true,
      "durableQueuePath": ".blyp/connectors.sqlite",
      "retry": {
        "maxAttempts": 8,
        "initialBackoffMs": 500,
        "maxBackoffMs": 30000,
        "multiplier": 2,
        "jitter": true
      }
    },
    "posthog": {
      "enabled": true,
      "mode": "auto",
      "projectKey": process.env.POSTHOG_PROJECT_KEY,
      "errorTracking": {
        "enabled": true,
        "mode": "auto"
      }
    },
    "sentry": {
      "enabled": true,
      "mode": "auto",
      "dsn": process.env.SENTRY_DSN
    },
    "otlp": [
      {
        "name": "grafana",
        "enabled": true,
        "mode": "auto",
        "endpoint": process.env.OTLP_HTTP_ENDPOINT
      }
    ]
  }
};

Default behavior

Redaction config

Use redact to remove sensitive values before they reach Blyp sinks:

export default {
  redact: {
    keys: ["internal_token"],
    paths: ["user.ssn", "payment.**.raw"],
    patterns: [/MY_ORG_[A-Z0-9]{32}/],
    disablePatternScanning: false,
  },
};

The redaction config supports:

Notes:

Database logging config

Use destination: "database" when local file persistence is not a good fit, especially in serverless deployments.

Database mode requires an executable config file such as blyp.config.ts, blyp.config.mts, blyp.config.js, or blyp.config.cjs because Prisma and Drizzle adapters are runtime objects. blyp.config.json cannot hold adapter instances by itself.

The config flag is only one part of the setup. The database must also match the required Blyp schema contract documented in Schema Contract.

import { PrismaClient } from "@prisma/client";
import { createPrismaDatabaseAdapter } from "@blyp/core/database";

const prisma = new PrismaClient();

export default {
  destination: "database",
  database: {
    dialect: "postgres",
    adapter: createPrismaDatabaseAdapter({
      client: prisma,
      model: "blypLog",
    }),
    delivery: {
      strategy: "batch",
      batchSize: 50,
      flushIntervalMs: 1000,
    },
  },
};

The database delivery config supports:

Use Database for the full setup flow, Schema Contract for the required table and indexes, and Database Migrations for the CLI migration workflow.

Connector delivery queue config

Use connectors.delivery when retryable server-side connector failures should spill into Blyp's internal queue instead of being dropped immediately:

export default {
  connectors: {
    delivery: {
      enabled: true,
      durableQueuePath: ".blyp/connectors.sqlite",
      memoryBufferSize: 500,
      durableSpillStrategy: "after-first-failure",
      memoryBatchSize: 25,
      sqliteWriteBatchSize: 100,
      sqliteReadBatchSize: 50,
      dispatchConcurrency: 4,
      pollIntervalMs: 1000,
      overflowStrategy: "drop-oldest",
      retry: {
        maxAttempts: 8,
        initialBackoffMs: 500,
        maxBackoffMs: 30000,
        multiplier: 2,
        jitter: true,
      },
    },
    betterstack: {
      enabled: true,
      mode: "auto",
      sourceToken: process.env.BETTERSTACK_TOKEN,
      ingestingHost: "https://in.logs.betterstack.com",
    },
  },
};

The connector delivery config supports:

Notes:

Common server adapter options

createLogger({
  level: "debug",
  pretty: false,
  logDir: "logs/api",
  file: {
    rotation: {
      maxSizeBytes: 5 * 1024 * 1024,
      maxArchives: 3,
      compress: true,
    },
  },
  autoLogging: {
    ignore: (ctx) => false,
  },
  customProps: (ctx) => ({
    requestId: "req_123",
  }),
  logErrors: true,
  ignorePaths: ["/health", "/metrics/**"],
  clientLogging: {
    path: "/client-ingest",
    validate: async (_ctx, payload) => payload.id !== "blocked",
    enrich: async (_ctx, payload) => ({
      clientLevel: payload.level,
    }),
  },
});

Connector config

Connectors live under connectors:

export default {
  connectors: {
    posthog: {
      enabled: true,
      mode: "auto",
      projectKey: process.env.POSTHOG_PROJECT_KEY,
      errorTracking: {
        enabled: true,
        mode: "auto",
        enableExceptionAutocapture: true,
      },
    },
    sentry: {
      enabled: true,
      mode: "auto",
      dsn: process.env.SENTRY_DSN,
      environment: process.env.NODE_ENV,
      release: process.env.RELEASE_SHA,
    },
    otlp: [
      {
        name: "grafana",
        enabled: true,
        mode: "auto",
        endpoint: process.env.OTLP_HTTP_ENDPOINT,
        auth: process.env.OTLP_AUTH_HEADER,
        serviceName: "api",
      },
    ],
  },
};

Notes that matter in production

Config helpers from the root package

import {
  getConfig,
  loadConfig,
  mergeBlypConfig,
  resolveConfig,
  resetConfigCache,
  type ResolvedBlypConfig,
} from "@blyp/core";

loadConfig(), resolveConfig(), and getConfig() now return ResolvedBlypConfig, so the returned shape includes normalized defaults for destination, file, clientLogging, connector readiness, and database delivery.

Use these if you need to inspect or recompute configuration in tests or custom bootstrap code.

Use Connectors for provider-specific behavior and manual APIs.