logv2

logv2 is MongoDB's structured-logging system. Every log line is a JSON object with a stable numeric id, a component, a severity, a message template, and a key-value map of attributes. The full reference is docs/logging.md (~25 KB).

Purpose

The system replaced the original printf-style server log in MongoDB 4.4. Goals:

• Structured output — every line is JSON; downstream tools (log aggregators, tests) consume it without regex.
• Stable identifiers — every call site has a unique id so log lines can be programmatically matched.
• Per-component severity — verbosity is tunable per component (command, replication, storage, etc.) at runtime.

Authoring a log line

#include "mongo/logv2/log.h"

LOGV2(123456,
      "Did the thing",
      "ns"_attr = nss,
      "count"_attr = count);

Macros:

• LOGV2(id, msg, attrs...) — informational.
• LOGV2_DEBUG(id, level, msg, attrs...) — debug at the given level (1..5).
• LOGV2_INFO, LOGV2_WARNING, LOGV2_ERROR, LOGV2_FATAL — severity-tagged variants.

The first argument is the log id. Each call site needs a unique id. IDs are reserved per team via etc/log_id_ranges.yml. The id is checked at compile time by clang-tidy.

Attribute formatting

"name"_attr = value invokes a customization point that must produce a JSON-serializable representation. Standard library types, BSON types, Status, and most domain types have specializations under src/mongo/logv2/. To log a custom type, provide a to_log_attr_format(...) overload.

Components

Each call site is associated with a component declared in src/mongo/logv2/log_component.cpp. The current set includes default, command, replication, sharding, storage, network, query, index, ftdc, and many more. Per-component verbosity is tunable at runtime:

db.adminCommand({
  setParameter: 1,
  logComponentVerbosity: {
    storage: { verbosity: 2 },
    command: { verbosity: 1 },
  },
});

Output

By default, mongod/mongos writes JSON to stdout (or a file via --logpath). Each line looks like:

{
  "t": { "$date": "2026-04-30T12:34:56.789+00:00" },
  "s": "I",
  "c": "COMMAND",
  "id": 123456,
  "ctx": "conn7",
  "msg": "Did the thing",
  "attr": { "ns": "test.coll", "count": 42 }
}

The t, s, c, id, ctx, and msg keys are mandated; attr carries the user-supplied data. The ctx field is the per-thread name set by the transport layer — conn7, replWriterWorker-3, etc.

Format and severity

Severities follow Apache log4j conventions:

Severity	Meaning
F	Fatal — the process is about to abort.
E	Error — recoverable but unexpected.
W	Warning — degraded behavior.
I	Info — operational events.
D1–D5	Debug at increasing verbosity.

Sinks

The framework ships a JSON sink (default), a plain-text sink (legacy, used in some test environments), and a syslog sink. The plumbing is in src/mongo/logv2/log_manager.cpp and src/mongo/logv2/log_domain*.

Performance

• Attribute formatting is deferred — LOGV2(...) only formats attributes if the line will actually be emitted.
• Each call site has a static descriptor inspected via the log_metric_initializer (src/mongo/logv2/log_metric_initializer/) for log-once and rate-limit semantics.

Key source files

File	Purpose
src/mongo/logv2/log.h	Public macros (LOGV2, LOGV2_DEBUG, …).
src/mongo/logv2/log_attr.h	The _attr UDL and attribute formatting.
src/mongo/logv2/log_component.cpp	Component registry and verbosity table.
src/mongo/logv2/log_manager.cpp	Sinks and global setup.
src/mongo/logv2/log_truncation.h	Truncates very large attributes.
etc/log_id_ranges.yml	Per-team log-id reservations.

Integration points

• The transport layer sets the per-connection context (ctx field).
• The op observer and commands framework emit operational logs at well-known ids.
• FTDC does not route through logv2 — it writes binary diagnostic data separately.
• OpenTelemetry export shares some metadata with logv2 (the operation id and trace id appear in both).

Entry points for modification

Adding a new log line means picking an unused id from your team's range, picking the right component and severity, and writing the call. New attribute types need a to_log_attr_format overload (see existing examples in src/mongo/db/curop.cpp). Ranges that need to be expanded are negotiated through etc/log_id_ranges.yml. The unit tests in src/mongo/logv2/*_test.cpp are good usage references.