grafana-logger/README.md

A functional logging package for Grafana with structured JSON output

# Grafana Logger - TypeScript/Node.js

A structured logging library designed for Grafana with JSON output.

## Installation

```bash
npm install grafana-logger
```

## Usage

### Basic Logging

```javascript
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

```javascript
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

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

### Performance Timing

```javascript
logger.time("database_query")

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

### Child Logger

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

### Advanced Usage

```javascript
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