Skip to content

Update UDP docs for the new executor #260

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
jachris wants to merge 5 commits into
base: topic/new-executor
Choose a base branch
from
Open

Update UDP docs for the new executor #260

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
7a0828f
Add to_udp operator documentation
jachris Apr 15, 2026
44d8406
Remove legacy UDP operator docs
jachris Apr 15, 2026
139956b
Clarify to_udp message types
jachris Apr 15, 2026
da3fb7d
Use string in to_udp docs
jachris Apr 15, 2026
63be852
Document accept_udp instead of from_udp
jachris Apr 23, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions src/content/docs/guides/collecting/get-data-from-the-network.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -61,11 +61,11 @@ high-volume, loss-tolerant data like syslog messages or metrics.

### Receive UDP datagrams

Use <Op>from_udp</Op> to receive UDP messages as
Use <Op>accept_udp</Op> to receive UDP messages as
structured events:

```tql
from_udp "0.0.0.0:514"
accept_udp "0.0.0.0:514"
```

Each datagram becomes an event with `data` (the message content) and `peer`
Expand All @@ -76,7 +76,7 @@ Each datagram becomes an event with `data` (the message content) and `peer`
A common pattern is receiving syslog over UDP:

```tql
from_udp "0.0.0.0:514"
accept_udp "0.0.0.0:514"
this = data.parse_syslog()
```

Expand All @@ -85,7 +85,7 @@ this = data.parse_syslog()
Include the sender's IP address and collection timestamp in your events:

```tql
from_udp "0.0.0.0:514"
accept_udp "0.0.0.0:514"
syslog = data.parse_syslog()
this = {
...syslog,
Expand Down
4 changes: 2 additions & 2 deletions src/content/docs/guides/collecting/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ TQL provides two types of input operators:
a [subpipeline](/reference/programs/#parsing-subpipelines).

- **Direct event operators** like <Op>from_kafka</Op>
and <Op>from_udp</Op> produce structured events
and <Op>accept_udp</Op> produce structured events
directly without an intermediate byte stream.

:::caution[Migration note]
Expand Down Expand Up @@ -78,7 +78,7 @@ interfaces:

```tql
// UDP syslog receiver
from_udp "0.0.0.0:514"
accept_udp "0.0.0.0:514"

// TCP with TLS
from "tcp://0.0.0.0:8443", tls=true
Expand Down
6 changes: 3 additions & 3 deletions src/content/docs/integrations/syslog.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,10 +22,10 @@ Together, these building blocks enable round-trip Syslog processing.
### Create a Syslog Server

To receive Syslog messages on a UDP socket, use
<Op>from_udp</Op>:
<Op>accept_udp</Op>:

```tql
from_udp "0.0.0.0:514"
accept_udp "0.0.0.0:514"
this = data.parse_syslog()
publish "syslog"
```
Expand Down Expand Up @@ -201,7 +201,7 @@ from {
message: " PARENT process running...",
}
write_syslog
save_udp "1.2.3.4:514"
to_udp "1.2.3.4:514"
Copy link
Copy Markdown

@chatgpt-codex-connector chatgpt-codex-connector Bot Apr 15, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Preserve syslog payload when switching to to_udp

This example now pipes write_syslog directly into to_udp without a message argument, but to_udp defaults to sending each input event as compact JSON when message is omitted. In this specific pipeline, that changes the wire payload from a raw RFC 5424 syslog line to JSON-encoded output, so readers following the example will not actually emit the message format described below the snippet.

Useful? React with 👍 / 👎.

```

This pipeline sends the following RFC 5424-formatted message to
Expand Down
11 changes: 5 additions & 6 deletions src/content/docs/integrations/udp.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,21 +14,20 @@ Use the IP address `0.0.0.0` to listen on all available network interfaces.

## Examples

Use <Op>from_udp</Op> to receive UDP datagrams as
structured events containing message data and peer information. For sending, use
<Op>save_udp</Op> with a write operator.
Use <Op>accept_udp</Op> to receive UDP datagrams as
structured events containing message data and peer information. Use <Op>to_udp</Op>
to send one UDP datagram per event directly from structured data.

### Receive syslog messages over UDP

```tql
from_udp "0.0.0.0:514"
accept_udp "0.0.0.0:514"
this = data.parse_syslog()
```

### Send events to a UDP socket

```tql
from {message: "Tenzir"}
write_ndjson
save_udp "1.2.3.4:8080"
to_udp "1.2.3.4:8080", message=message
```
34 changes: 11 additions & 23 deletions src/content/docs/reference/operators.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -391,10 +391,10 @@ operators:
description: 'Retrieves PowerQuery results from SentinelOne Singularity Data Lake.'
example: 'from_sentinelone_data_lake "https://…", …'
path: 'reference/operators/from_sentinelone_data_lake'
- name: 'from_udp'
- name: 'accept_udp'
description: 'Receives UDP datagrams and outputs structured events.'
example: 'from_udp "0.0.0.0:8090"'
path: 'reference/operators/from_udp'
example: 'accept_udp "0.0.0.0:8090"'
path: 'reference/operators/accept_udp'
- name: 'from_velociraptor'
description: 'Submits VQL to a Velociraptor server and returns the response as events.'
example: 'from_velociraptor subscribe="Windows"'
Expand Down Expand Up @@ -451,10 +451,6 @@ operators:
description: 'Loads bytes from a TCP or TLS connection.'
example: 'load_tcp "0.0.0.0:8090" { read_json }'
path: 'reference/operators/load_tcp'
- name: 'load_udp'
description: 'Loads bytes from a UDP socket.'
example: 'load_udp "0.0.0.0:8090"'
path: 'reference/operators/load_udp'
- name: 'load_zmq'
description: 'Receives ZeroMQ messages.'
example: 'load_zmq'
Expand Down Expand Up @@ -691,10 +687,10 @@ operators:
description: 'Saves bytes to a TCP or TLS connection.'
example: 'save_tcp "0.0.0.0:8090", tls=true'
path: 'reference/operators/save_tcp'
- name: 'save_udp'
description: 'Saves bytes to a UDP socket.'
example: 'save_udp "0.0.0.0:8090"'
path: 'reference/operators/save_udp'
- name: 'to_udp'
description: 'Sends one UDP datagram per input event.'
example: 'to_udp "127.0.0.1:514"'
path: 'reference/operators/to_udp'
- name: 'save_zmq'
description: 'Sends bytes as ZeroMQ messages.'
example: 'save_zmq'
Expand Down Expand Up @@ -2134,14 +2130,6 @@ load_tcp "0.0.0.0:8090" { read_json }

</ReferenceCard>

<ReferenceCard title="load_udp" description="Loads bytes from a UDP socket." href="/reference/operators/load_udp">

```tql
load_udp "0.0.0.0:8090"
```

</ReferenceCard>

<ReferenceCard title="load_zmq" description="Receives ZeroMQ messages." href="/reference/operators/load_zmq">

```tql
Expand Down Expand Up @@ -2269,10 +2257,10 @@ from_sentinelone_data_lake "https://…", …

</ReferenceCard>

<ReferenceCard title="from_udp" description="Receives UDP datagrams and outputs structured events." href="/reference/operators/from_udp">
<ReferenceCard title="accept_udp" description="Receives UDP datagrams and outputs structured events." href="/reference/operators/accept_udp">

```tql
from_udp "0.0.0.0:8090"
accept_udp "0.0.0.0:8090"
```

</ReferenceCard>
Expand Down Expand Up @@ -2490,10 +2478,10 @@ save_tcp "0.0.0.0:8090", tls=true

</ReferenceCard>

<ReferenceCard title="save_udp" description="Saves bytes to a UDP socket." href="/reference/operators/save_udp">
<ReferenceCard title="to_udp" description="Sends one UDP datagram per input event." href="/reference/operators/to_udp">
Copy link
Copy Markdown

@chatgpt-codex-connector chatgpt-codex-connector Bot Apr 15, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Place to_udp in the Events operator section

This new card is inserted in the bytes CardGrid (between save_udp and save_zmq) even though to_udp is documented as an event output operator (category: Outputs/Events in reference/operators/to_udp.mdx). On /reference/operators, users browse by section headings, so keeping to_udp under bytes makes it easy to miss and misclassifies its usage model. Move it to the Events section so discoverability and categorization match the operator contract.

Useful? React with 👍 / 👎.


```tql
save_udp "0.0.0.0:8090"
to_udp "127.0.0.1:514"
```

</ReferenceCard>
Expand Down
18 changes: 8 additions & 10 deletions ...ent/docs/reference/operators/from_udp.mdx → ...t/docs/reference/operators/accept_udp.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,22 +1,21 @@
---
title: from_udp
title: accept_udp
category: Inputs/Events
example: 'from_udp "0.0.0.0:8090"'
example: 'accept_udp "0.0.0.0:8090"'
---

Receives UDP datagrams and outputs structured events.

```tql
from_udp endpoint:string, [resolve_hostnames=bool], [binary=bool]
accept_udp endpoint:string, [resolve_hostnames=bool], [binary=bool]
```

## Description

Listens for UDP datagrams on the specified endpoint and outputs each datagram as
a structured event containing the data and peer information.

Unlike <Op>load_udp</Op>, which outputs raw bytes,
`from_udp` produces structured events with metadata about the sender.
`accept_udp` produces structured events with metadata about the sender.

### `endpoint: string`

Expand Down Expand Up @@ -59,7 +58,7 @@ Each UDP datagram produces one event with the following structure:
### Receive UDP datagrams with sender information

```tql
from_udp "0.0.0.0:1234"
accept_udp "0.0.0.0:1234"
```

This might output events like:
Expand All @@ -77,20 +76,19 @@ This might output events like:
### Parse JSON data from UDP datagrams

```tql
from_udp "127.0.0.1:8080"
accept_udp "127.0.0.1:8080"
select data = data.parse_json()
```

### Filter by sender and decode data

```tql
from_udp "0.0.0.0:9999"
accept_udp "0.0.0.0:9999"
where peer.ip == 192.168.1.100
select data
```

## See Also

- <Op>load_udp</Op>
- <Op>save_udp</Op>
- <Op>to_udp</Op>
- <Integration>udp</Integration>
1 change: 0 additions & 1 deletion src/content/docs/reference/operators/from.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -150,7 +150,6 @@ load_tcp "tcp://0.0.0.0:12345", parallel=10 {
| `s3` | <Op>load_s3</Op> | `from "s3://bucket/file.json"` |
| `sqs` | <Op>load_sqs</Op> | `from "sqs://my-queue" { read_json }` |
| `tcp` | <Op>load_tcp</Op> | `from "tcp://127.0.0.1:13245" { read_json }` |
| `udp` | <Op>load_udp</Op> | `from "udp://127.0.0.1:56789" { read_json }` |
| `zmq` | <Op>load_zmq</Op> | `from "zmq://127.0.0.1:56789" { read_json }` |
Comment on lines 152 to 153
Copy link
Copy Markdown

@chatgpt-codex-connector chatgpt-codex-connector Bot Apr 23, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Restore UDP scheme mapping in from URI table

Removing the udp row from the from URI-scheme table makes the reference internally inconsistent: other docs in this repo still instruct users to run from "udp://..." (for example, reference/operators/assert_throughput.mdx), so readers can no longer discover the documented UDP from path from the canonical scheme list. Either keep the UDP mapping here or update all remaining UDP-URI usage docs in the same change.

Useful? React with 👍 / 👎.


Please see the respective operator pages for details on the URI's locator format.
Expand Down
55 changes: 0 additions & 55 deletions src/content/docs/reference/operators/load_udp.mdx
View file
Open in desktop

This file was deleted.

37 changes: 0 additions & 37 deletions src/content/docs/reference/operators/save_udp.mdx
View file
Open in desktop

This file was deleted.

1 change: 0 additions & 1 deletion src/content/docs/reference/operators/to.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -97,7 +97,6 @@ If no scheme is present, the connector attempts to save to the local filesystem.
| `s3` | <Op>save_s3</Op> | `to "s3://bucket/file.json"` |
| `sqs` | <Op>save_sqs</Op> | `to "sqs://my-queue" { write_json }` |
| `tcp` | <Op>save_tcp</Op> | `to "tcp://127.0.0.1:56789" { write_json }` |
| `udp` | <Op>save_udp</Op> | `to "udp://127.0.0.1:56789" { write_json }` |
| `zmq` | <Op>save_zmq</Op> | `to "zmq://127.0.0.1:56789" { write_json }` |
| `smtp`, `smtps`, `mailto`, `email` | <Op>save_email</Op> | `to "smtp://john@example.com"` |

Expand Down
Loading
Loading