Skip to main content
The forwarder sink sends data to another Tell instance over TCP. Use it for edge-to-cloud deployments where edge nodes collect data locally and relay it to a central server.

​
Configuration

[sinks.upstream]
type = "forwarder"
target = "central-tell.example.com:50000"
api_key = "abcdef0123456789abcdef0123456789"
FieldDefaultNotes
target—Remote Tell server address as host:port (required)
api_key—32-character hex streaming key for the remote server (required)

​
How it works

The forwarder receives batches from the router, rebuilds each FlatBuffer message with:
  • The remote server’s API key (replacing the local key)
  • The original client’s source IP preserved in the source_ip field
The remote Tell server receives the data as if the original client connected directly, preserving IP-based analytics.

​
Protocol

The forwarder uses the same length-prefixed FlatBuffer protocol as Tell’s TCP source: 
[4 bytes: length (big-endian)][N bytes: FlatBuffer batch]
The receiving server must have forwarding_mode = true on its TCP source to honor the source_ip field: 
# On the central server
[[sources.tcp]]
port = 50000
forwarding_mode = true
Without forwarding_mode, the central server would record the edge node’s IP instead of the original client’s IP.

​
Reliability

  • Auto-reconnect — reconnects automatically if the connection drops, with configurable retry intervals
  • Retry with backoff — 3 retry attempts per message with 1-second intervals
  • TCP keep-alive — enabled by default (30-second interval) to detect dead connections
  • Per-message forwarding — if one message fails, remaining messages in the batch still attempt delivery

​
Edge deployment pattern

A typical edge-to-cloud setup: 
# Edge node config
[[sources.tcp]]
port = 50000

[sinks.upstream]
type = "forwarder"
target = "central.example.com:50000"
api_key = "abcdef0123456789abcdef0123456789"

[routing]
default = ["upstream"]
SDKs connect to the edge node. The edge node forwards everything to the central server. You can also add local sinks for redundancy: 
[routing]
default = ["upstream", "local_archive"]