### Example: Temperature Monitoring Logs

Source: https://github.com/julien-r44/pino-loki/blob/dev/_autodocs/api-reference/formatLog.md

An example demonstrating log formatting for temperature monitoring using a string template.

```APIDOC
## Examples

### Temperature Monitoring Logs

```typescript
import { LogBuilder } from 'pino-loki'

const builder = new LogBuilder()

const log = builder.build({
  log: {
    level: 30,
    msg: 'Temperature check',
    lokilevel: 'info',
    sensor: { id: 'temp-001', value: 72.5, unit: 'F' },
    time: Date.now(),
    hostname: 'sensor-hub',
  },
  logFormat: 'SENSOR:{sensor.id} VALUE:{sensor.value}{sensor.unit}',
})
// Message: "SENSOR:temp-001 VALUE:72.5F"
```
```

--------------------------------

### Pino-Loki CLI Usage Example

Source: https://github.com/julien-r44/pino-loki/blob/dev/README.md

Install and use pino-loki globally via npm. This snippet shows how to pipe logs from a file to the pino-loki CLI, specifying a custom Loki hostname.

```shell
npm install -g pino-loki
node foo | pino-loki --hostname=http://hostname:3100
```

--------------------------------

### Install pino-loki

Source: https://github.com/julien-r44/pino-loki/blob/dev/_autodocs/README.md

Install the pino-loki package using npm.

```bash
npm install pino-loki
```

--------------------------------

### Direct Usage Transport Setup (Not Recommended for Production)

Source: https://github.com/julien-r44/pino-loki/blob/dev/_autodocs/api-reference/pinoLoki.md

Direct usage of the pino-loki transport without worker threads. Batching is disabled in this example.

```typescript
import { pino } from 'pino'
import { pinoLoki } from 'pino-loki'

const logger = pino(
  { level: 'info' },
  pinoLoki({
    host: 'http://localhost:3100',
    basicAuth: {
      username: 'user',
      password: 'pass',
    },
    batching: false,
  }),
)

logger.info('Message without batching')
```

--------------------------------

### Debug Logging Setup

Source: https://github.com/julien-r44/pino-loki/blob/dev/_autodocs/module-map.md

Demonstrates how to set up and use the debug logger for pino-loki.

```typescript
import { debuglog } from 'node:util'
export default debuglog('pino-loki')
```

```bash
DEBUG=pino-loki node app.js
```

```typescript
import debug from './debug.ts'
debug('Message with %s', 'format')
```

--------------------------------

### Example: Multi-level Format with Function

Source: https://github.com/julien-r44/pino-loki/blob/dev/_autodocs/api-reference/formatLog.md

An example showcasing complex log formatting using a function that includes conditional logic.

```APIDOC
### Multi-level Format with Function

```typescript
const formatted = formatLog({
  log: {
    time: 1718894400000,
    level: 50,
    msg: 'Authentication failed',
    lokilevel: 'error',
    user: { id: 'user-123', email: 'test@example.com' },
    attempts: 3,
  },
  logFormat: (log) => {
    if (log.attempts && log.attempts > 5) {
      return `SECURITY ALERT: ${log.user.email} exceeded attempts`
    }
    return `Auth error: ${log.msg}`
  }
})
// Returns: "Auth error: Authentication failed"
```
```

--------------------------------

### Complete Loki Push API URL Examples

Source: https://github.com/julien-r44/pino-loki/blob/dev/_autodocs/endpoints.md

Examples of complete URLs for the Loki Push API, including local and remote instances.

```plaintext
http://localhost:3100/loki/api/v1/push
https://loki.example.com:3100/loki/api/v1/push
https://logs-prod.grafana.net/loki/api/v1/push
```

--------------------------------

### Pino-Loki Configuration Examples

Source: https://github.com/julien-r44/pino-loki/blob/dev/_autodocs/types.md

Demonstrates different ways to configure batching options for pino-loki, including default, custom, and disabled batching.

```typescript
import type { LokiOptions } from 'pino-loki'

// Default batching (5s interval, 10000 max)
const opts1: LokiOptions = { host: 'http://localhost:3100' }

// Custom batching
const opts2: LokiOptions = {
  host: 'http://localhost:3100',
  batching: { interval: 10, maxBufferSize: 5000 },
}

// Disable batching
const opts3: LokiOptions = {
  host: 'http://localhost:3100',
  batching: false,
}
```

--------------------------------

### Authorization Header Example

Source: https://github.com/julien-r44/pino-loki/blob/dev/_autodocs/endpoints.md

Demonstrates how to configure basic authentication credentials, which pino-loki then encodes and sends in the Authorization header.

```typescript
basicAuth: { username: 'user', password: 'pass' }
// Generates: Authorization: Basic dXNlcjpwYXNz
```

--------------------------------

### CLI Argument Parsing Setup

Source: https://github.com/julien-r44/pino-loki/blob/dev/_autodocs/module-map.md

Shows how to define and use CLI argument options with Node.js's parseArgs utility.

```typescript
export const options = {
  'version': { type: 'boolean', short: 'v', help: '...' },
  'hostname': { type: 'string', default: '...', help: '...' },
  // ... 16 more options
} as const
```

```typescript
import { options } from './args.ts'
import { parseArgs } from 'node:util'

const { values } = parseArgs({ options })
```

--------------------------------

### Custom Log Formatting Examples

Source: https://github.com/julien-r44/pino-loki/blob/dev/_autodocs/types.md

Demonstrates how to configure Pino-Loki with different `logFormat` options: string template, function, and disabled.

```typescript
import type { LokiOptions, LogFormat } from 'pino-loki'

// String template
const opts1: LokiOptions = {
  host: 'http://localhost:3100',
  logFormat: '{time} | {lokilevel} | {msg}',
}

// Function
const opts2: LokiOptions = {
  host: 'http://localhost:3100',
  logFormat: (log) => {
    return `[${log.lokilevel.toUpperCase()}] ${log.msg || 'no message'}`
  },
}

// Disabled
const opts3: LokiOptions = {
  host: 'http://localhost:3100',
  logFormat: false,
}
```

--------------------------------

### Worker Thread Transport Setup

Source: https://github.com/julien-r44/pino-loki/blob/dev/_autodocs/api-reference/pinoLoki.md

Recommended setup for using pino-loki as a worker thread transport. Configure host and basic authentication for Loki.

```typescript
import pino from 'pino'
import type { LokiOptions } from 'pino-loki'

const transport = pino.transport<LokiOptions>({
  target: 'pino-loki',
  options: {
    host: 'https://loki.example.com:3100',
    basicAuth: {
      username: 'user',
      password: 'pass',
    },
  },
})

const logger = pino(transport)
logger.info('Hello, Loki!')
```

--------------------------------

### Development Setup with Pino Transport

Source: https://github.com/julien-r44/pino-loki/blob/dev/_autodocs/quick-reference.md

Configure Pino to use the pino-loki transport for development, sending logs immediately.

```typescript
const transport = pino.transport<LokiOptions>({
  target: 'pino-loki',
  options: {
    host: 'http://localhost:3100',
    batching: false, // Send immediately
    silenceErrors: false, // See errors
    labels: { env: 'dev' },
  },
})
```

--------------------------------

### PinoLog Example

Source: https://github.com/julien-r44/pino-loki/blob/dev/_autodocs/types.md

An example of a Pino log object with various properties including level, message, and custom context.

```typescript
const pinoLog: PinoLog = {
  level: 30,
  msg: 'User created',
  userId: 123,
  email: 'user@example.com',
  time: 1718894400000,
  hostname: 'app-server-1',
  pid: 12345,
}
```

--------------------------------

### Function Format Example

Source: https://github.com/julien-r44/pino-loki/blob/dev/_autodocs/api-reference/formatLog.md

Illustrates using formatLog with a function for dynamic log formatting based on log content.

```APIDOC
## Function Format

### Example

```typescript
const formatted = formatLog({
  log: { time: 1718894400000, level: 30, msg: 'Test', lokilevel: 'info' },
  logFormat: (log) => `[${log.lokilevel.toUpperCase()}] ${log.msg}`
})
// Returns: "[INFO] Test"
```

### Behavior

- Directly calls the function with the log object
- Return value is used as the formatted string
```

--------------------------------

### Structured Metadata with Default Key

Source: https://github.com/julien-r44/pino-loki/blob/dev/README.md

Example of sending structured metadata using the default 'meta' key in a Pino log.

```javascript
logger.info({ meta: { recordId: 123, traceId: 456 } }, 'Hello')
// -> { recordId: 123, traceId: 456 } sent as structured metadata
```

--------------------------------

### String Template Format Example

Source: https://github.com/julien-r44/pino-loki/blob/dev/_autodocs/api-reference/formatLog.md

Demonstrates how to use formatLog with a string template for log formatting, including nested properties.

```APIDOC
## String Template Format

### Example

```typescript
const formatted = formatLog({
  log: {
    time: 1718894400000,
    level: 30,
    msg: 'Request received',
    lokilevel: 'info',
    req: { method: 'POST', url: '/api/users' },
  },
  logFormat: '{time} | {level} | {msg} | {req.method} {req.url}'
})
// Returns: "1718894400000 | 30 | Request received | POST /api/users"
```

### Behavior

- Searches for patterns matching `{key}` where key can include dots for nested access
- Replaces each pattern with the corresponding value from the log object
- Uses the `get()` utility to safely access nested properties (supports dot notation like `{req.method}`)
- Empty placeholders or missing properties are replaced with empty string
```

--------------------------------

### Full Loki Push API Request Body Example

Source: https://github.com/julien-r44/pino-loki/blob/dev/_autodocs/endpoints.md

A comprehensive example of the request body for the Loki Push API, demonstrating multiple streams with various labels and log entries, including structured metadata.

```json
{
  "streams": [
    {
      "stream": {
        "level": "info",
        "hostname": "prod-server",
        "app": "payment-service",
        "env": "production",
        "userId": "user-456"
      },
      "values": [
        ["1718894400123456789", "{\"msg\":\"Payment processed\",\"amount\":99.99}"],
        ["1718894401234567890", "{\"msg\":\"Receipt sent\",\"email\":\"user@example.com\"}", {"traceId": "abc-123", "spanId": "def-456"}]
      ]
    },
    {
      "stream": {
        "level": "error",
        "hostname": "prod-server",
        "app": "payment-service",
        "env": "production",
        "userId": "user-789"
      },
      "values": [
        ["1718894402345678901", "{\"msg\":\"Payment failed\",\"error\":\"Insufficient funds\"}"]
      ]
    }
  ]
}
```

--------------------------------

### LokiLogLevel Usage Example

Source: https://github.com/julien-r44/pino-loki/blob/dev/_autodocs/types.md

Demonstrates how to import and use LokiLogLevel constants to map Pino log levels to Loki log levels.

```typescript
import { LokiLogLevel } from 'pino-loki'

const levelMap = {
  10: LokiLogLevel.Debug,
  30: LokiLogLevel.Info,
  50: LokiLogLevel.Error,
}
```

--------------------------------

### High-Performance Setup with Pino Transport

Source: https://github.com/julien-r44/pino-loki/blob/dev/_autodocs/quick-reference.md

Configure Pino for high performance by increasing batching intervals and buffer sizes, and silencing errors.

```typescript
const transport = pino.transport<LokiOptions>({
  target: 'pino-loki',
  options: {
    host: 'https://loki.example.com',
    batching: {
      interval: 30,        // Less frequent sends
      maxBufferSize: 100000, // Large buffer
    },
    timeout: 60000,
    silenceErrors: true, // Don't block on errors
  },
})
```

--------------------------------

### Streams Array Format Example

Source: https://github.com/julien-r44/pino-loki/blob/dev/_autodocs/endpoints.md

An example illustrating the format of the 'streams' array in the request body, including stream labels and log entry values with optional structured metadata.

```typescript
{
  stream: {
    level: 'info',
           // Loki log level
    hostname: 'app-server-1', // Always included
    app: 'my-app',           // From labels option
    environment: 'prod',      // From labels option
    userId: '123',            // From propsToLabels
  },
  values: [
    [timestamp_ns, message_json],
    [timestamp_ns, message_json, structured_metadata],
  ]
}
```

--------------------------------

### Configure Basic Authentication

Source: https://github.com/julien-r44/pino-loki/blob/dev/_autodocs/configuration.md

Provide username and password for HTTP Basic Authentication. Examples show direct credentials and usage with environment variables.

```typescript
{
  basicAuth: {
    username: 'my-username',
    password: 'my-password',
  }
}
```

```typescript
{
  basicAuth: {
    username: process.env.LOKI_USERNAME!,
    password: process.env.LOKI_PASSWORD!,
  }
}
```

--------------------------------

### Production Setup with Pino Transport

Source: https://github.com/julien-r44/pino-loki/blob/dev/_autodocs/quick-reference.md

Configure Pino for production, using environment variables for sensitive information and enabling batching.

```typescript
const transport = pino.transport<LokiOptions>({
  target: 'pino-loki',
  options: {
    host: process.env.LOKI_HOST!,
    basicAuth: {
      username: process.env.LOKI_USER!,
      password: process.env.LOKI_PASSWORD!,
    },
    headers: {
      'X-Scope-OrgID': process.env.LOKI_ORG_ID,
    },
    batching: {
      interval: 10,
      maxBufferSize: 50000,
    },
    labels: {
      app: 'my-app',
      environment: 'production',
    },
    propsToLabels: ['userId', 'requestId'],
    silenceErrors: true,
    timeout: 15000,
  },
})
```

--------------------------------

### Minimal Request Example

Source: https://github.com/julien-r44/pino-loki/blob/dev/_autodocs/endpoints.md

Send a single log entry with minimal labels to the Loki push endpoint.

```typescript
// Single log with minimal labels
fetch('http://localhost:3100/loki/api/v1/push', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    streams: [
      {
        stream: {
          level: 'info',
          hostname: 'server-1',
        },
        values: [
          ['1718894400000000000', '{"msg":"Hello"}'],
        ],
      },
    ],
  }),
})
```

--------------------------------

### LokiLog Structure Example

Source: https://github.com/julien-r44/pino-loki/blob/dev/_autodocs/types.md

Illustrates the expected structure of a LokiLog object, including stream labels and log entries with optional structured metadata.

```typescript
{
  stream: {
    level: 'info',
    hostname: 'server-1',
    app: 'my-app',
    env: 'prod',
  },
  values: [
    ['1718894400000000000', '{"msg":"Hello","level":30}'],
    // or with structured metadata
    ['1718894401000000000', '{"msg":"World"}', { userId: '123' }],
  ]
}
```

--------------------------------

### Custom Headers Example

Source: https://github.com/julien-r44/pino-loki/blob/dev/_autodocs/endpoints.md

Shows how to add custom headers to requests sent to the Loki Push API using the 'headers' option.

```typescript
headers: {
  'X-Scope-OrgID': 'org-123',
  'X-Custom-Header': 'value',
}
// Sends both headers with every request
```

--------------------------------

### Configure Loki Host

Source: https://github.com/julien-r44/pino-loki/blob/dev/_autodocs/configuration.md

Set the base URL for your Loki instance. Include the protocol and port. Examples cover local development, remote instances, and Grafana Cloud.

```typescript
{ host: 'http://localhost:3100' }
```

```typescript
{ host: 'https://loki.example.com:3100' }
```

```typescript
{ host: 'https://logs-prod.grafana.net' }
```

--------------------------------

### Log Formatting Implementation

Source: https://github.com/julien-r44/pino-loki/blob/dev/_autodocs/api-reference/get.md

Illustrates how the `get` function is used internally by `formatLog` to extract values for string templates in log formatting.

```typescript
// In formatLog implementation, this enables:
// Template: '{req.method} {req.url}'
// Values: get(log, 'req.method') and get(log, 'req.url')
```

--------------------------------

### CLI Integration Example

Source: https://github.com/julien-r44/pino-loki/blob/dev/_autodocs/api-reference/validateHeaders.md

Shows how validateHeaders can be used within a CLI argument parsing context, like in 'createPinoLokiConfigFromArgs'. It handles cases where headers might be undefined.

```typescript
// In createPinoLokiConfigFromArgs
const headers = values.headers ? validateHeaders(values.headers) : undefined

// Usage in CLI:
// pino-loki --hostname=http://localhost:3100 --headers="X-Scope-OrgID=org-123,X-API-Key=secret"
```

--------------------------------

### Using Default Structured Metadata Key

Source: https://github.com/julien-r44/pino-loki/blob/dev/_autodocs/configuration.md

Logs will automatically include structured metadata under the default 'meta' key. This example shows how to pass metadata with a log message.

```typescript
logger.info({ meta: { userId: 123, traceId: 'abc' } }, 'Message')
```

--------------------------------

### Batching Control for Logs

Source: https://github.com/julien-r44/pino-loki/blob/dev/_autodocs/quick-reference.md

Configures how logs are batched before sending to Loki. This example shows enabling batching with custom interval and buffer size, and disabling batching to send logs immediately.

```typescript
// Enable with custom settings
{
  batching: {
    interval: 10,        // Send every 10 seconds
    maxBufferSize: 5000, // Max 5000 logs in buffer
  }
}

// Disable batching (send immediately)
{
  batching: false
}
```

--------------------------------

### Validate Headers in Pino-Loki

Source: https://github.com/julien-r44/pino-loki/blob/dev/_autodocs/errors.md

Shows how to use the `validateHeaders` function to check for correct header formats. It highlights valid and invalid header string examples.

```typescript
import { validateHeaders } from 'pino-loki'

// Valid
validateHeaders('X-Header=value') // OK

// Invalid - missing separator
validateHeaders('X-Header') 
// Throws: Invalid header format: "X-Header". Expected format is "key=value".

// Invalid - empty value
validateHeaders('X-Header=')
// Throws: Invalid header format: "X-Header=". Expected format is "key=value".
```

--------------------------------

### Custom Pino-Loki Transport with Log Formatting

Source: https://github.com/julien-r44/pino-loki/blob/dev/_autodocs/configuration.md

Example of creating a custom Pino transport target for pino-loki, allowing for custom log formatting when using worker threads.

```typescript
// main.ts
import pino from 'pino'

const logger = pino({
  transport: {
    target: './custom-pino-loki.js',
    options: { host: 'http://localhost:3100' },
  },
})
```

```typescript
// custom-pino-loki.js
import { pinoLoki } from 'pino-loki'

export default function customTransport(options) {
  return pinoLoki({
    ...options,
    logFormat: (log) => {
      return `[${log.lokilevel}] ${log.msg}`
    },
  })
}
```

--------------------------------

### Full pino-loki Transport Configuration

Source: https://github.com/julien-r44/pino-loki/blob/dev/_autodocs/types.md

Illustrates a comprehensive configuration for the pino-loki transport, including all available options such as endpoint, timeout, batching, labels, authentication, and custom log formatting. Use this example when advanced customization is needed.

```typescript
import type { LokiOptions } from 'pino-loki'
import pino from 'pino'

// Full configuration
const fullOptions: LokiOptions = {
  host: 'https://loki.example.com:3100',
  endpoint: '/loki/api/v1/push',
  timeout: 15000,
  silenceErrors: false,
  batching: {
    interval: 10,
    maxBufferSize: 5000,
  },
  replaceTimestamp: false,
  labels: {
    app: 'my-app',
    environment: 'production',
  },
  levelMap: {
    30: 'info',
    50: 'error',
  },
  basicAuth: {
    username: 'user',
    password: 'pass',
  },
  headers: {
    'X-Scope-OrgID': 'org-123',
  },
  propsToLabels: ['userId', 'requestId'],
  convertArrays: true,
  structuredMetaKey: 'meta',
  logFormat: '{time} | {level} | {msg}',
}
```

--------------------------------

### Configure Pino-Loki Transport in Worker Thread

Source: https://github.com/julien-r44/pino-loki/blob/dev/README.md

Use this snippet to set up the pino-loki transport to run in a worker thread. Ensure you have pino and pino-loki installed. Replace placeholder credentials and host with your Loki instance details.

```typescript
import pino from 'pino'
import type { LokiOptions } from 'pino-loki'

const transport = pino.transport<LokiOptions>({
  target: "pino-loki",
  options: {
    host: 'https://my-loki-instance:3100',
    basicAuth: {
      username: "username",
      password: "password",
    },
  },
});

const logger = pino(transport);
logger.error({ foo: 'bar' })
```

--------------------------------

### Convert Pino Log Level to Loki Log Level

Source: https://github.com/julien-r44/pino-loki/blob/dev/_autodocs/api-reference/LogBuilder.md

Shows how to use the statusFromLevel method to convert a numerical Pino log level into its corresponding Loki log level string based on the builder's configured level map. Includes examples for known levels and a fallback for unknown levels.

```typescript
const builder = new LogBuilder()
builder.statusFromLevel(30) // Returns 'info'
builder.statusFromLevel(50) // Returns 'error'
builder.statusFromLevel(999) // Returns 'info' (default fallback)
```

--------------------------------

### Basic Usage of pino-loki

Source: https://github.com/julien-r44/pino-loki/blob/dev/_autodocs/api-reference/createPinoLokiConfigFromArgs.md

Demonstrates the basic command-line usage of pino-loki, requiring only the hostname for the Loki instance.

```bash
node foo | pino-loki --hostname=http://loki:3100
```

--------------------------------

### Handle RequestError in pino-loki

Source: https://github.com/julien-r44/pino-loki/blob/dev/_autodocs/errors.md

Example of how to catch and handle a RequestError when pushing logs to Loki. It demonstrates checking the error type and accessing the error message and response body.

```typescript
import { LogPusher } from 'pino-loki'

const pusher = new LogPusher({
  host: 'http://localhost:3100',
  basicAuth: { username: 'invalid', password: 'wrong' },
})

try {
  await pusher.push({ level: 30, msg: 'Test' })
} catch (err) {
  if (err instanceof RequestError) {
    console.error('Loki error:', err.message)
    console.error('Response:', err.responseBody)
  }
}
```

--------------------------------

### Basic CLI Usage

Source: https://github.com/julien-r44/pino-loki/blob/dev/_autodocs/quick-reference.md

Connect to a local Loki instance using the CLI.

```bash
# Basic
pino-loki --hostname http://localhost:3100
```

--------------------------------

### Custom Error Monitoring with Pino-Loki

Source: https://github.com/julien-r44/pino-loki/blob/dev/_autodocs/errors.md

Extend the LogPusher class to implement custom error monitoring logic. This example increments an error count and triggers an alert if the count exceeds a threshold.

```typescript
// Wrap LogPusher to add error tracking
class MonitoredLogPusher extends LogPusher {
  constructor(options) {
    super(options)
    this.errorCount = 0
  }
  
  async push(logs) {
    try {
      await super.push(logs)
    } catch (err) {
      this.errorCount++
      if (this.errorCount > 10) {
        console.alert('Too many Loki errors!')
      }
      throw err
    }
  }
}
```

--------------------------------

### pino-loki with Authentication

Source: https://github.com/julien-r44/pino-loki/blob/dev/_autodocs/api-reference/createPinoLokiConfigFromArgs.md

Shows how to configure pino-loki with authentication credentials (username and password) for a secure Loki instance.

```bash
node app.js | pino-loki \
  --hostname=https://loki.example.com:3100 \
  --user=myuser \
  --password=mypass
```

--------------------------------

### get Function Usage for Property Access

Source: https://github.com/julien-r44/pino-loki/blob/dev/_autodocs/module-map.md

Illustrates how to use the get function to safely access nested properties of an object with a default value.

```typescript
import { get } from 'pino-loki'

const obj = { user: { name: 'Alice' } }
const name = get(obj, 'user.name', 'Unknown') // 'Alice'
```

--------------------------------

### get Function Signature

Source: https://github.com/julien-r44/pino-loki/blob/dev/_autodocs/api-reference/get.md

This is the TypeScript signature for the get utility function. It specifies the types for the input value, path, and default value, as well as the return type.

```typescript
function get<TDefault = unknown>(
  value: any,
  path: string,
  defaultValue?: TDefault
): TDefault
```

--------------------------------

### Type Safety with pino-loki get

Source: https://github.com/julien-r44/pino-loki/blob/dev/_autodocs/api-reference/get.md

Highlights the type safety provided by the `get` function through its generic type parameter, which infers the return type based on the path and the provided default value.

```typescript
const result1 = get(obj, 'user.name', 'default') // Type: string
const result2 = get(obj, 'count', 0) // Type: number
const result3 = get(obj, 'data') // Type: unknown

// Type inference based on default
const email: string = get(obj, 'user.email', '')
const count: number = get(obj, 'metrics.count', 0)
```

--------------------------------

### pino-loki Help and Version Commands

Source: https://github.com/julien-r44/pino-loki/blob/dev/_autodocs/api-reference/createPinoLokiConfigFromArgs.md

Illustrates how to display the help message or the version information for the pino-loki CLI tool.

```bash
pino-loki --help
```

```bash
pino-loki --version
```

--------------------------------

### Pino-Loki CLI Help Options

Source: https://github.com/julien-r44/pino-loki/blob/dev/README.md

Displays all available command-line options for the pino-loki CLI. Use these flags to configure hostname, authentication, batching, timeouts, and label management.

```shell
$ pino-loki -h
Options:
  -v, --version                          Print version number and exit
  -u, --user <user>                      Loki username
  -p, --password <password>              Loki password
  --hostname <hostname>                  URL for Loki (default: http://localhost:3100)
  --endpoint <endpoint>                  Path to the Loki push API (default: /loki/api/v1/push)
  --headers <headers>                    Headers to be sent to Loki (Example: "X-Scope-OrgID=your-id,another=value")
  -b, --batching                         Should logs be sent in batch mode (default: true)
  -i, --batching-interval <interval>     The interval at which batched logs are sent in seconds (default: 5)
  --batching-max-buffer-size <size>      Maximum number of logs to buffer (default: 10000, 0 for unlimited)
  -t, --timeout <timeout>                Timeout for request to Loki in ms (default: 30000)
  -s, --silenceErrors                    If set, errors will not be displayed in the console
  -r, --replaceTimestamp                 Replace pino logs timestamps with Date.now()
  -l, --labels <label>                   Additional labels to be added to all Loki logs (JSON)
  --convertArrays                        If set, arrays will be converted to objects
  --propsLabels <labels>                 Fields in log line to convert to Loki labels (comma separated)
  --structuredMetaKey <key>              Key for structured metadata (default: 'meta', use 'false' to disable)
  -h, --help                             Print this help message and exit
```

--------------------------------

### get Function Signature and Usage

Source: https://github.com/julien-r44/pino-loki/blob/dev/_autodocs/api-reference/get.md

This snippet details the signature of the get utility function and provides an overview of its parameters and return value. It's designed for safely accessing nested properties in objects or arrays using dot and bracket notation.

```APIDOC
## get

### Description
A utility function for safely accessing nested properties in objects or arrays using dot and bracket notation.

### Signature
```typescript
function get<TDefault = unknown>(value: any, path: string, defaultValue?: TDefault): TDefault
```

### Parameters
#### Path Parameters
- **value** (any) - Required - The object or array to extract from
- **path** (string) - Required - Dot notation path to the property (e.g., `'user.profile.name'`)
- **defaultValue** (TDefault) - Optional - Value to return if the path doesn't exist

### Return Value
Returns the value at the specified path or the `defaultValue` if the path cannot be resolved. The return type is `TDefault`.

### Behavior
- Parses the path using regex to split on dots, brackets, and closing brackets
- Iterates through each segment of the path to traverse the object
- Returns the `defaultValue` if any intermediate value is `null` or `undefined`
- Safely handles quoted keys by removing quotes
- Skips empty segments in the path
- Returns `defaultValue` if the final value is `undefined`

### Path Syntax
The function supports multiple notation styles:

| Syntax | Example | Result |
|--------|---------|--------|
| Dot notation | `user.name` | Access nested object properties |
| Bracket notation | `user[profile][name]` | Same as dot notation |
| Quoted keys | `user['first-name']` | Access keys with special characters |
| Mixed notation | `items[0].name` | Combine dot and bracket notations |
```

--------------------------------

### Initialize and Use LogBuilder

Source: https://github.com/julien-r44/pino-loki/blob/dev/_autodocs/module-map.md

Demonstrates how to initialize the LogBuilder with custom options for propsToLabels and levelMap, and then use it to build a LokiLog object from a Pino log. Useful for transforming Pino logs into the Loki format.

```typescript
import { LogBuilder } from 'pino-loki'

const builder = new LogBuilder({
  propsToLabels: ['userId'],
  levelMap: { 50: 'critical' },
})

const lokiLog = builder.build({
  log: pinoLog,
  additionalLabels: { app: 'my-app' },
})
```

--------------------------------

### Instantiate LogBuilder and Build Loki Log

Source: https://github.com/julien-r44/pino-loki/blob/dev/_autodocs/api-reference/LogBuilder.md

Demonstrates how to create a LogBuilder instance with custom label extraction and level mapping, and then use it to convert a Pino log entry to Loki format. This includes adding additional labels and specifying properties to be used as Loki labels.

```typescript
import { LogBuilder } from 'pino-loki'

const builder = new LogBuilder({
  propsToLabels: ['userId', 'requestId'],
  levelMap: {
    30: 'info',
    50: 'critical', // Override default
  },
})

const pino log = {
  level: 30,
  msg: 'User action',
  userId: '123',
  requestId: 'req-abc',
  time: 1718894400000,
  hostname: 'server-1',
}

const lokiLog = builder.build({
  log,
  additionalLabels: { app: 'my-app', env: 'prod' },
  propsToLabels: ['userId', 'requestId'],
})

// lokiLog.stream.level === 'info'
// lokiLog.stream.userId === '123'
// lokiLog.stream.requestId === 'req-abc'
// lokiLog.stream.app === 'my-app'
// lokiLog.stream.env === 'prod'
// lokiLog.values[0][0] === nanosecond timestamp string
```

--------------------------------

### Custom Headers for Loki

Source: https://github.com/julien-r44/pino-loki/blob/dev/README.md

Example of adding custom headers, such as 'X-Scope-OrgID', for Loki requests.

```typescript
{
  "X-Scope-OrgID": "your-id",
})
```

--------------------------------

### get Function

Source: https://github.com/julien-r44/pino-loki/blob/dev/_autodocs/module-map.md

Retrieves a nested property from an object using dot notation. This is an internal utility.

```APIDOC
## Function get

### Description
Safely retrieves a nested property from an object using a dot-separated path. It returns a default value if the path does not exist. Note: This is an internal utility and not part of the primary public API.

### Signature
`function get<TDefault = unknown>(value: any, path: string, defaultValue?: TDefault): TDefault`

### Parameters
- **value** (any) - Required - The object to retrieve the property from.
- **path** (string) - Required - The dot-separated path to the nested property (e.g., 'user.address.city').
- **defaultValue** (TDefault) - Optional - The value to return if the path is not found.

### Returns
- TDefault - The value of the nested property or the defaultValue if not found.
```

--------------------------------

### pino-loki with Custom Labels

Source: https://github.com/julien-r44/pino-loki/blob/dev/_autodocs/api-reference/createPinoLokiConfigFromArgs.md

Illustrates how to add custom labels to logs by providing a JSON string to the --labels argument.

```bash
node app.js | pino-loki \
  --hostname=http://localhost:3100 \
  --labels='{"app":"my-app","env":"production"}'
```

--------------------------------

### Initialize LogPusher and Push Logs

Source: https://github.com/julien-r44/pino-loki/blob/dev/_autodocs/api-reference/LogPusher.md

Demonstrates how to instantiate LogPusher with Loki connection details and authentication, then push single or multiple log entries.

```typescript
import { LogPusher } from 'pino-loki'

const pusher = new LogPusher({
  host: 'http://localhost:3100',
  basicAuth: {
    username: 'user',
    password: 'pass',
  },
})

// Push a single log
await pusher.push({
  level: 30,
  msg: 'User logged in',
  userId: 123,
  time: Date.now(),
})

// Push multiple logs
await pusher.push([
  { level: 30, msg: 'First log', time: Date.now() },
  { level: 40, msg: 'Second log', time: Date.now() },
])
```

--------------------------------

### Import pino-loki as Named and Default

Source: https://github.com/julien-r44/pino-loki/blob/dev/_autodocs/module-map.md

Demonstrates how to import the pino-loki library using both named and default export syntaxes. Useful for integrating the library into your project.

```typescript
import { pinoLoki, LokiOptions } from 'pino-loki'

// Import default
import pinoLoki from 'pino-loki'

// TypeScript type imports
import type { LokiOptions, PinoLog } from 'pino-loki'
```

--------------------------------

### Print Help Function Usage

Source: https://github.com/julien-r44/pino-loki/blob/dev/_autodocs/module-map.md

Demonstrates how to use the printHelp function to display CLI help text based on argument options.

```typescript
import { printHelp } from './print_help.ts'
import { options } from './args.ts'

printHelp(options)
```

--------------------------------

### Pino-Loki Project File Structure

Source: https://github.com/julien-r44/pino-loki/blob/dev/_autodocs/quick-reference.md

Overview of the distribution directory structure for the pino-loki package.

```bash
dist/
├── index.cjs          # CommonJS entry (default: pinoLoki)
├── index.mjs          # ES module entry (default: pinoLoki)
├── index.d.cts        # CJS type definitions
├── index.d.mts        # ESM type definitions
└── cli.mjs            # CLI executable
```

--------------------------------

### get Utility Function

Source: https://github.com/julien-r44/pino-loki/blob/dev/_autodocs/MANIFEST.txt

A utility function for safely accessing nested properties within objects using dot or bracket notation.

```APIDOC
## get

### Description
Utility function to safely retrieve nested properties from an object using dot or bracket notation.

### Signature
`get<T>(obj: object, path: string | string[], defaultValue?: any): T`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **obj** (object) - Required - The object to retrieve the property from.
- **path** (string | string[]) - Required - The path to the property (e.g., 'a.b.c' or ['a', 'b', 'c']).
- **defaultValue** (any) - Optional - The default value to return if the property is not found.

### Request Example
```javascript
const { get } = require('pino-loki')

const data = {
  user: {
    profile: {
      name: 'John Doe'
    }
  },
  tags: ['a', 'b']
}

const name = get(data, 'user.profile.name')
console.log(name) // Output: John Doe

const firstTag = get(data, ['tags', 0])
console.log(firstTag) // Output: a

const nonExistent = get(data, 'user.age', 30)
console.log(nonExistent) // Output: 30
```

### Response
#### Success Response
- **T** - The value of the property at the specified path, or the default value if not found.

#### Response Example
```javascript
// Example output from Request Example:
// John Doe
// a
// 30
```
```

--------------------------------

### createPinoLokiConfigFromArgs Function

Source: https://github.com/julien-r44/pino-loki/blob/dev/_autodocs/MANIFEST.txt

Parses command-line arguments to create a configuration object for the Pino-Loki transport.

```APIDOC
## createPinoLokiConfigFromArgs

### Description
Parses CLI arguments to generate a configuration object for the Pino-Loki transport.

### Signature
`createPinoLokiConfigFromArgs(args: string[]): LokiOptions`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **args** (string[]) - Required - An array of command-line arguments.

### Request Example
```javascript
const { createPinoLokiConfigFromArgs } = require('pino-loki')

const cliArgs = [
  '--loki-url=http://localhost:3100',
  '--loki-batching-size=100'
]

const config = createPinoLokiConfigFromArgs(cliArgs)
console.log(config)
```

### Response
#### Success Response
- **LokiOptions** - An object containing the configuration for the Pino-Loki transport.

#### Response Example
```json
{
  "url": "http://localhost:3100",
  "batching": {
    "size": 100
  }
}
```
```

--------------------------------

### CLI Usage with Authentication

Source: https://github.com/julien-r44/pino-loki/blob/dev/_autodocs/quick-reference.md

Connect to a remote Loki instance with basic authentication via the CLI.

```bash
# With authentication
pino-loki \
  --hostname https://loki.example.com:3100 \
  --user myuser \
  --password mypass
```

--------------------------------

### HTTP Endpoint Specification

Source: https://github.com/julien-r44/pino-loki/blob/dev/_autodocs/MANIFEST.txt

Details on the HTTP endpoints provided by the pino-loki transport, including their methods, paths, parameters, request/response formats, and examples.

```APIDOC
## HTTP Endpoint Details

This section details the HTTP endpoints available for integration with pino-loki.

### Endpoints Reference

This document provides details on the HTTP endpoints for integration purposes. It refers to the Types Reference for data structures used in requests and responses.

**Example Usage:** Integration developers can use this reference to understand how to send logs to the pino-loki transport via HTTP.

**Note:** Specific HTTP methods, paths, request bodies, and response schemas are detailed within the 'Endpoints Reference' document itself, which is not fully detailed in this summary.
```

--------------------------------

### Configure pino-loki via CLI Arguments

Source: https://github.com/julien-r44/pino-loki/blob/dev/_autodocs/configuration.md

Use the pino-loki command-line tool with various arguments to configure connection details, batching, labels, and more.

```bash
pino-loki \
  --hostname http://localhost:3100 \
  --user username \
  --password password \
  --batching true \
  --batching-interval 5 \
  --batching-max-buffer-size 10000 \
  --timeout 30000 \
  --labels '{"app":"my-app"}' \
  --propsLabels userId,requestId \
  --headers "X-Scope-OrgID=org-id" \
  --convertArrays false \
  --structuredMetaKey meta \
  --silenceErrors false \
  --replaceTimestamp false
```

--------------------------------

### LogPusher Initialization and Usage

Source: https://github.com/julien-r44/pino-loki/blob/dev/_autodocs/module-map.md

Demonstrates how to initialize the LogPusher class and send logs to a Loki instance.

```typescript
import { LogPusher } from 'pino-loki'

const pusher = new LogPusher({ host: 'http://localhost:3100' })
await pusher.push([log1, log2])
```

--------------------------------

### Use Case: Grafana Cloud Headers

Source: https://github.com/julien-r44/pino-loki/blob/dev/_autodocs/api-reference/validateHeaders.md

Example of using validateHeaders to parse headers specifically for Grafana Cloud Loki instances, such as 'X-Scope-OrgID'.

```typescript
const headers = validateHeaders('X-Scope-OrgID=12345')
// For Grafana Cloud Loki instances
```

--------------------------------

### Array-like Access on Non-Arrays

Source: https://github.com/julien-r44/pino-loki/blob/dev/_autodocs/api-reference/get.md

Shows the behavior of `get` when attempting array-like access (e.g., `[0]`) on a non-array type, returning the default value.

```typescript
// Array-like access on non-arrays
const obj = { data: 'string' }
get(obj, 'data[0]', 'default') // Returns: 'default' (string doesn't have numeric keys)
```

--------------------------------

### createPinoLokiConfigFromArgs Function

Source: https://github.com/julien-r44/pino-loki/blob/dev/_autodocs/module-map.md

Parses command-line arguments to create a LokiOptions configuration object.

```APIDOC
## Function createPinoLokiConfigFromArgs

### Description
Parses command-line arguments provided to the CLI tool and converts them into a `LokiOptions` object, which can be used to configure the `LogPusher`.

### Returns
- LokiOptions - An object containing configuration options derived from CLI arguments.
```

--------------------------------

### Handling Null/Undefined Intermediate Values

Source: https://github.com/julien-r44/pino-loki/blob/dev/_autodocs/api-reference/get.md

Illustrates how the `get` function handles intermediate `null` or `undefined` values in the path, returning the default value.

```typescript
// Null/undefined intermediate values
const obj = { user: null }
get(obj, 'user.name', 'default') // Returns: 'default' (null terminates traversal)
```

--------------------------------

### printHelp Function

Source: https://github.com/julien-r44/pino-loki/blob/dev/_autodocs/module-map.md

Prints the command-line interface help text to the console.

```APIDOC
## Function printHelp

### Description
Prints formatted help text for the CLI tool to standard output. This function is typically invoked when the user provides the `--help` flag.

### Signature
`function printHelp(opts: CustomParseArgsOptionsConfig): void`

### Parameters
- **opts** (CustomParseArgsOptionsConfig) - Required - The configuration object defining the CLI arguments and their properties, used to generate the help text.
```

--------------------------------

### Configure Loki Endpoint

Source: https://github.com/julien-r44/pino-loki/blob/dev/_autodocs/configuration.md

Specify the HTTP path for the Loki push API. The default is 'loki/api/v1/push'. Examples show the default, an alternative, and a full URL endpoint.

```typescript
{ endpoint: 'loki/api/v1/push' }
```

```typescript
{ endpoint: '/v1/push' }
```

```typescript
{ endpoint: 'http://other-host:3100/custom/path' }
```

--------------------------------

### LogBuilder.build

Source: https://github.com/julien-r44/pino-loki/blob/dev/_autodocs/api-reference/LogBuilder.md

Converts a single Pino log entry into the Loki log format, applying configured labels, level mapping, and formatting.

```APIDOC
## LogBuilder.build

### Description
Converts a single Pino log entry to Loki log format, supporting custom labels, timestamp handling, and message formatting.

### Signature
```typescript
build(options: {
  log: PinoLog
  replaceTimestamp?: boolean
  additionalLabels?: Record<string, string>
  convertArrays?: boolean
  structuredMetaKey?: string | false
  logFormat?: LogFormat
}): LokiLog
```

### Parameters
#### options
- **log** (`PinoLog`, Required): The Pino log object to convert.
- **replaceTimestamp** (`boolean`, Optional, Default: `false`): If true, uses the current time instead of the log's timestamp.
- **additionalLabels** (`Record<string, string>`, Optional): Extra labels to add to all converted logs.
- **convertArrays** (`boolean`, Optional, Default: `false`): If true, converts arrays to objects with numeric string keys.
- **structuredMetaKey** (`string | false`, Optional, Default: `'meta'`): The key containing structured metadata; set to `false` to disable.
- **logFormat** (`LogFormat`, Optional): A format string or function to customize the log output.

### Return Value
Returns a `LokiLog` object containing `stream` and `values` properties.

### Behavior
1. **Timestamp handling**: Converts Pino timestamp to nanoseconds; supports millisecond and nanosecond inputs.
2. **Hostname extraction**: Removes hostname from log object to use as a dedicated label.
3. **Level mapping**: Converts Pino level number to Loki level string.
4. **Labels construction**: Includes configured additional labels, extracts labels from log properties based on `propsToLabels`, and always includes the level and hostname.
5. **Message formatting**: Uses custom formatting if `logFormat` is provided, otherwise JSON stringifies the log object. Arrays are converted to indexed objects if `convertArrays` is true.
6. **Structured metadata**: Extracts from the configured key, converting non-string values to strings.

### Example
```javascript
import { LogBuilder } from 'pino-loki'

const builder = new LogBuilder({
  propsToLabels: ['userId', 'requestId'],
  levelMap: {
    30: 'info',
    50: 'critical',
  },
})

const pinoLog = {
  level: 30,
  msg: 'User action',
  userId: '123',
  requestId: 'req-abc',
  time: 1718894400000,
  hostname: 'server-1',
}

const lokiLog = builder.build({
  log: pinoLog,
  additionalLabels: { app: 'my-app', env: 'prod' },
})

// lokiLog.stream.level === 'info'
// lokiLog.stream.userId === '123'
// lokiLog.stream.requestId === 'req-abc'
// lokiLog.stream.app === 'my-app'
// lokiLog.stream.env === 'prod'
// lokiLog.values[0][0] === nanosecond timestamp string
```
```

--------------------------------

### pinoLoki Transport Factory

Source: https://github.com/julien-r44/pino-loki/blob/dev/_autodocs/MANIFEST.txt

The main transport factory function for creating a Pino-Loki transport instance. It handles the configuration and setup for sending logs to Grafana Loki.

```APIDOC
## pinoLoki

### Description
Factory function to create the Pino-Loki transport. It takes configuration options and returns a Pino transport stream.

### Signature
pinoLoki(options: LokiOptions): Pino.TransportStream

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **options** (LokiOptions) - Required - Configuration object for the transport.

### Request Example
```javascript
const pino = require('pino')
const { pinoLoki } = require('pino-loki')

const transport = pino.transport({
  target: pinoLoki,
  options: {
    // Loki transport options here
  }
})

const logger = pino(transport)
logger.info('hello world')
```

### Response
#### Success Response
- **Pino.TransportStream** - A Pino transport stream that can be used to pipe logs.

#### Response Example
(Stream object, not directly representable as JSON)
```

--------------------------------

### Import Patterns for pino-loki

Source: https://github.com/julien-r44/pino-loki/blob/dev/_autodocs/quick-reference.md

Demonstrates different ways to import the pino-loki library, including the main function, named imports with types, and type-only imports.

```typescript
// Main function
import pinoLoki from 'pino-loki'

// Named imports
import { pinoLoki, LokiLogLevel, type LokiOptions } from 'pino-loki'

// Type-only imports
import type { LokiOptions, PinoLog, BatchingOptions } from 'pino-loki'
```

--------------------------------

### Handling Empty Path Segments

Source: https://github.com/julien-r44/pino-loki/blob/dev/_autodocs/api-reference/get.md

Demonstrates that the `get` function correctly skips empty segments in the path, allowing for paths like 'user..name'.

```typescript
// Empty path segments
get(obj, 'user..name', 'default') // Skips empty segments, works normally
```

--------------------------------

### pino-loki with Custom Headers

Source: https://github.com/julien-r44/pino-loki/blob/dev/_autodocs/api-reference/createPinoLokiConfigFromArgs.md

Demonstrates how to send custom HTTP headers with log requests to Loki by specifying them as comma-separated key-value pairs.

```bash
node app.js | pino-loki \
  --hostname=https://loki.example.com:3100 \
  --headers="X-Scope-OrgID=my-org-id,X-Custom-Header=value"
```

--------------------------------

### pino-loki Extracting Fields as Labels

Source: https://github.com/julien-r44/pino-loki/blob/dev/_autodocs/api-reference/createPinoLokiConfigFromArgs.md

Demonstrates how to use the --propsLabels argument to extract specific log fields and convert them into labels for Loki.

```bash
node app.js | pino-loki \
  --hostname=http://localhost:3100 \
  --propsLabels=userId,requestId,service
```