---
sidebar_position: 1
title: Logging
---

# Logging

Certeasy uses structured logging with configurable level, format, output, and per-service overrides.

## Configuration

```yaml
logs:
  level: info
  format: json
  output: file
  file: "/var/log/certeasy/certeasy.log"
  rotate:
    max-size-mb: 100
    max-backups: 10
  services:
    DB-Driver: warn
    Certeasy-acme-server: debug
  tags:
    instance: cert-srv-01
    region: eu-west
```

## Fields

| Field | Default | Description |
|---|---|---|
| `level` | `info` | Global log level: `debug`, `info`, `warn`, `error`, `off`. `off` (alias `none`) fully suppresses logs and is most useful as a per-service override. |
| `format` | `json` | Log format: `json` or `text` |
| `output` | `stderr` | Output destination: `stderr`, `stdout`, or `file` |
| `file` | — | Log file path. Required if `output: file`. |
| `rotate.max-size-mb` | — | Max log file size in MB before rotation |
| `rotate.max-backups` | — | Number of rotated log files to keep |
| `services` | empty | Per-service log level overrides |
| `tags` | empty | User-defined labels added to every log entry — useful for Grafana/Loki filtering |

## Per-Service Log Levels

You can set a different log level for each internal service. This is useful for debugging a specific component without flooding logs with debug output from everything else.

```yaml
logs:
  level: info
  services:
    Certeasy-acme-server: debug
    Async-Acme-Challenges: debug
```

Use `off` (or `none`) to fully silence a service — for example when a chatty driver is generating noise during dev or staging captures:

```yaml
logs:
  services:
    DB-Driver: off
    Certeasy-acme-server: warn
```

### Registered Service Names

| Service Name | Description |
|---|---|
| `DB-Driver` | Database driver and query logs |
| `adcs` | ADCS authority operations |
| `Certeasy-acme-server` | ACME HTTP request handling |
| `Async-Acme-Pki-Handler` | Async PKI job processing |
| `Async-Acme-Challenges` | Async challenge validation |
| `JWKS` | JWS key validation |
| `worker` | Job engine (lease, dispatch, backoff) |
| `http-server` | HTTP server lifecycle |

## Tags (Grafana/Loki labels)

`logs.tags` is a free-form map of `key: value` pairs added to **every** log entry. Use it to attach environment metadata that your log aggregator (Grafana/Loki, Splunk, Elastic…) can filter on.

```yaml
logs:
  tags:
    instance: cert-srv-01
    region: eu-west
    role: production
```

Each entry shows up as a top-level field in the JSON output, alongside `time`, `level`, `msg`, etc. There is no fixed list of allowed keys — pick whatever your stack expects.

:::note
The previous automatic `env` field is no longer added to log entries; it conflicted with the `env=` shown inside license-related log messages (license environment, e.g. `env=dev` / `env=prod`). If you want an environment label, set it explicitly under `tags`.
:::

## Log Rotation

Log rotation is supported when `output: file`. Configure `rotate` to limit disk usage:

```yaml
logs:
  output: file
  file: "C:\\ProgramData\\certeasy\\certeasy.log"
  rotate:
    max-size-mb: 100
    max-backups: 5
```

This keeps up to 5 rotated files of 100 MB each (500 MB total).

## Production Recommendations

- Use `format: json` for structured log ingestion (Splunk, Elastic, Loki…)
- Use `output: file` with rotation to avoid filling disk
- Keep global level at `info` and only set `debug` on specific services when troubleshooting
- Route logs to your SIEM — the audit log entries contain account IDs, order IDs, and operation details