---
url: /logly.zig/guide/network-logging.md
description: >-
  Send logs over TCP and UDP with Logly.zig. Perfect for centralized logging,
  shipping to collectors like Logstash, and remote application monitoring.
---

# Network Logging

Logly supports sending logs over the network using TCP and UDP protocols. This is useful for centralized logging, shipping logs to log collectors (like Logstash, Fluentd, or Splunk), or monitoring applications remotely.

## Basic Usage

To enable network logging, add a network sink to your logger configuration.

```zig
const logly = @import("logly");

pub fn main() !void {
    var logger = try logly.Logger.init(allocator);
    defer logger.deinit();

    // TCP Sink
    var tcpSink = logly.SinkConfig.network("tcp://127.0.0.1:9000");
     _ = try logger.addSink(tcpSink);

    // UDP Sink
    var udpSink = logly.SinkConfig.network("udp://127.0.0.1:9001");
     _ = try logger.addSink(udpSink);

    try logger.info("This message goes to network sinks!", .{});
}
```

## Configuration Options

Network sinks support standard sink configuration options, plus protocol-specific behaviors.

### TCP vs UDP

* **TCP**: Reliable delivery. The logger will establish a connection and keep it open. If the connection drops, it will attempt to reconnect. Good for critical logs where delivery is guaranteed.
* **UDP**: Fire-and-forget. Faster and less overhead, but delivery is not guaranteed. Good for high-volume metrics or non-critical logs where occasional packet loss is acceptable.

### JSON Formatting

Network sinks are often used with log collectors that expect structured data. You can enable JSON formatting for the sink:

```zig
var sink = logly.SinkConfig.network("tcp://logs.example.com:5000");
sink.format = .json; // Send logs as JSON objects
 _ = try logger.addSink(sink);
```

### Colors

By default, network sinks do not send ANSI color codes. If you are streaming logs to a remote terminal or a viewer that supports ANSI colors, you can force enable them:

```zig
var sink = logly.SinkConfig.network("tcp://viewer.example.com:9000");
sink.color = true; // Force enable ANSI colors
 _ = try logger.addSink(sink);
```

## Example: Centralized Logging

You can set up a simple centralized logging server using `netcat` for testing:

**Server (Terminal 1):**

```bash
nc -l -k 9000
```

**Client (Zig Application):**

```zig
var sink = logly.SinkConfig.network("tcp://localhost:9000");
 _ = try logger.addSink(sink);
try logger.info("Hello from client!", .{});
```

## Network Helper APIs

Use the `Network` helpers directly when you need one-off sends outside of sinks:

```zig
const Network = logly.Network;

const stream = try Network.connectTcp(allocator, "tcp://127.0.0.1:9000");
defer stream.close(logly.Utils.io());
try Network.sendTcp(stream, "raw tcp log\n");

const udp = try Network.createUdpSocket(allocator, "udp://127.0.0.1:514");
defer udp.socket.close(logly.Utils.io());
try Network.sendSyslogUdp(
  allocator,
  udp.socket,
  udp.address,
  .user,
  .info,
  "localhost",
  "my-app",
  "syslog helper message",
);
```

## Reliability

* **Async Logging**: It is highly recommended to use `asyncWrite = true` (default) for network sinks to avoid blocking your application if the network is slow or the server is unreachable.
* **Buffering**: The async writer buffers logs and sends them in batches, improving network efficiency.
* **Reconnection**: TCP sinks handle reconnection logic automatically.

## Syslog over TCP (RFC 6587) (v0.2.0)

Logly `v0.2.0` introduces complete support for connection-oriented, reliable Syslog forwarding over TCP (conforming to RFC 6587). This completes the remote Syslog RFC 5424 suite by providing guaranteed delivery of secure event streams, whereas traditional UDP Syslog is "fire-and-forget" and prone to packet loss under congestion.

### Configuration

To send logs to a remote Syslog TCP daemon:

```zig
var syslogSink = logly.SinkConfig.syslog("tcp://syslog-collector:514");
syslogSink.facility = .local0;
syslogSink.severity = .info;
 _ = try logger.addSink(syslogSink);
```

Logly automatically takes care of packet framing (e.g. octet counting or non-transparent framing via newlines) and maintains robust reconnection loops to ensure zero log loss during brief collector downtime.

## Security

Currently, Logly supports plain TCP and UDP. For secure logging over public networks, consider using:

* SSH tunneling
* VPNs
* Stunnel
* A local log collector agent (e.g., Vector, Fluent Bit) that handles TLS encryption.

## See Also

* [Network API](/api/network) - Network reference API
* [Network Logging Example](/examples/network-logging) - High performance network logs example