---
url: /logly.zig/api/distributed.md
description: >-
  API reference for Logly.zig DistributedConfig struct. Configure service
  identification, tracing headers, and environment context for microservices.
---

# Distributed Config API

The `DistributedConfig` struct controls how the logger behaves in a distributed system, defining service identity and trace propagation rules.

## Fields

### `enabled: bool`

Enable distributed context features. When true, distributed fields (like service name, region) are automatically attached to logs.
**Default**: `false`

### Service Identity

#### `serviceName: ?[]const u8`

Name of the service or application (e.g., "auth-service", "payment-api").
**Default**: `null`

#### `serviceVersion: ?[]const u8`

Semantic version of the running artifact (e.g., "1.0.2", "v2.0.0-rc1").
**Default**: `null`

#### `environment: ?[]const u8`

Deployment environment (e.g., "production", "staging", "development").
**Default**: `null`

#### `datacenter: ?[]const u8`

Datacenter or Availability Zone identifier (e.g., "us-east-1a", "eu-west-2").
**Default**: `null`

#### `region: ?[]const u8`

Cloud region identifier (e.g., "us-east-1").
**Default**: `null`

#### `instanceId: ?[]const u8`

Unique identifier for the specific instance (e.g., Kubernetes Pod ID, EC2 Instance ID, container ID).
**Default**: `null`

### Trace Propagation

#### `traceHeader: []const u8`

HTTP header name used for propagating Trace IDs.
**Default**: `"X-Trace-ID"`

#### `spanHeader: []const u8`

HTTP header name used for propagating Span IDs.
**Default**: `"X-Span-ID"`

#### `parentHeader: []const u8`

HTTP header name used for propagating Parent Span IDs.
**Default**: `"X-Parent-ID"`

#### `baggageHeader: []const u8`

HTTP header name for Baggage/Correlation Context.
**Default**: `"Correlation-Context"`

#### `traceSamplingRate: f64`

Sampling probablity for distributed traces (0.0 to 1.0).
**Default**: `1.0` (100% sampling)

### Callbacks

#### `onTraceCreated: ?*const fn (traceId: []const u8) void`

Optional callback invoked whenever `logger.setTraceContext` is called.
**Default**: `null`

#### `onSpanCreated: ?*const fn (spanId: []const u8, name: []const u8) void`

Optional callback invoked whenever `logger.startSpan` is called.
**Default**: `null`

## Usage

```zig
var config = logly.Config.default();
config.distributed = .{
    .enabled = true,
    .serviceName = "payment-service",
    .environment = "production",
    .region = "us-east-1",
    .traceHeader = "b3-traceid", // Support B3 propagation headers
    .spanHeader = "b3-spanid",
};
```

## W3C Trace Context Interop

`DistributedConfig` controls service metadata and optional custom headers. For standards-based propagation, use the logger's W3C helpers:

```zig
const incoming = request.getHeader("traceparent") orelse "";
const reqLogger = try logger.withTraceparent(incoming);

// Nested operation
const child = reqLogger.child("7a085853722dc6d2").inModule("database.query");
try child.info("Executing query", @src());

// Forward to downstream call
if (try logger.getTraceparentHeader(allocator)) |traceparent| {
  defer allocator.free(traceparent);
  try outbound_headers.put("traceparent", traceparent);
}
```

`withTraceparent(...)` and `setTraceContextFromTraceparent(...)` return `LoggerError.InvalidTraceparent` for malformed headers.