Grafana Logger - TypeScript/Node.js

A structured logging library designed for Grafana with JSON output.

Installation

npm install grafana-logger

Usage

Basic Logging

import { gl } from "grafana-logger"

const logger = gl("my-service")

logger.info("Application started")
logger.warn("This is a warning")
logger.error("Something went wrong")
logger.debug("Debug information")
logger.fatal("Critical error")
logger.trace("Detailed trace information")

Fluent API with Chaining

import { gl } from "grafana-logger"
const logger = gl("cb-backend-server")

logger.component("auth").traceId("abc123").info("User logged in")

logger
    .component("database")
    .tag("slow-query")
    .tags(["performance", "optimization"])
    .warn("Query took longer than expected")

Request Logging

logger
    .requestPayload({
        method: "POST",
        path: "/api/users",
        user_id: "12345",
    })
    .component("api")
    .info("Processing request")

Performance Timing

logger.time("database_query")

// Later in your code...
logger.timeEnd("database_query")

Child Logger

const childLogger = logger.child({
    user_id: "12345",
    session_id: "sess_abc123",
})
childLogger.info("Child logger with additional metadata")

Advanced Usage

logger
    .component("payment-processor")
    .traceId("trace-456")
    .traceFile(__filename)
    .processId("worker-1")
    .tags(["payment", "critical"])
    .requestPayload({
        amount: 100.0,
        currency: "USD",
        customer_id: "cust_123",
    })
    .info("Processing payment")

API Reference

Main Function

• gl(service: string) -> Logger: Create a new logger instance for the specified service

Logger Methods

Builder Methods (return Logger for chaining)

• component(component: string): Set the component name
• traceFile(traceFile: string): Set the trace file path
• requestPayload(payload: object): Set the request payload
• processId(processId: string): Set the process ID (auto-filled with process.pid by default)
• traceId(traceId: string): Set the distributed tracing ID
• tags(tags: string[]): Set multiple tags
• tag(tag: string): Add a single tag

Logging Methods (log immediately and end the chain)

• debug(message: string): Log at debug level
• info(message: string): Log at info level
• warn(message: string): Log at warning level
• error(message: string): Log at error level
• fatal(message: string): Log at fatal level
• trace(message: string): Log at trace level
• child(metadata: object): Create a child logger with additional metadata
• time(name: string): Start a named timer
• timeEnd(name: string): End a named timer and log the duration