PortX ingest HTTP API
Push events into PortX over HTTP/S: the logger.jsp endpoint, the listener token, the hostName parameter, the JSON body and the reserved keys that place and type the log, the response codes, and the listener settings behind the endpoint.
What you will do: post JSON events to an HTTP/S listener from an application, a script or a shipper, and control where they land in the Folders and Logs tree.
The HTTP/S listener is the endpoint every shipper uses — Fluent Bit, Logstash, Kubernetes DaemonSets, your own code. Each listener account has a token; the token in the URL is the authentication and tells PortX which account the data belongs to. The endpoint speaks whatever protocol the server is configured for: HTTPS once the console is on HTTPS (TLS certificates), which the wiki strongly recommends.
The endpoint
POST https://<host>:<https port>/logeye/api/logger.jsp?token=<listener token>&hostName=<source>
Content-Type: application/json
{"message": "Your message to XPLG here"}
- Host and port — the console port on V7 (30303 HTTP, 30443 HTTPS); on X8 the listener role (30305, HTTPS 30445) or the Traefik listener pool.
token— required; the listener account's token, generated when you create the account and shown in its URL field.hostName— optional; names the source device the events come from, so that a listener set to split by source device creates one log per host.- Body — JSON with the event in
message, or a richer object when the listener's JSON settings pick the message key and split on other keys (below).
curl -k -X POST "https://<host>:30443/logeye/api/logger.jsp?token=<token>&hostName=app-01" \
-H "Content-Type: application/json" \
-d '{"message": "hello from app-01"}'
| Response | Meaning |
|---|---|
200 OK | The event was received |
400 Bad Request | Invalid format or a missing parameter (usually the token) |
500 Internal Server Error | The server could not process the request |
The wiki states no payload limit, batch format or throttling for the HTTP/S listener; both are pending engineering (the syslog listeners document 1,024 and 8,192 bytes per event; the capabilities page names throttling, no listener page documents a parameter).
Reserved keys in the body
| Key | Effect |
|---|---|
| The Message JSON Key of the account | Which field holds the log message; required when a template should be matched |
xpologPath | The folder path, ->-separated, where the log is stored |
xpologName | The log name (appended when another split type is also selected) |
xpologType | The log type; if a template with that type exists it is applied automatically — together with the Message JSON Key |
Logstash sets them with add_field in its filter; Fluent Bit carries the host in hostName and the rest in the record.
The listener account behind it
Create it under PortX > Data > Listen to Data (Manager > Data > Listen to Data on older builds); a change to a listener applies to data received from then on.
| Setting | Meaning |
|---|---|
| Name, Description | Identify the account |
| Listening Node | In a cluster, the node that receives the requests; the URL field fills in once it is chosen |
| Token | The authentication token, unique per account |
| Enabled | Whether the account is active |
| Parent Folder | Where the logs from this listener are created |
| Collection Policy | Storage location and retention for those logs — see Collection policies and archive |
| AppTags | Tags applied to the logs |
| Log Name Prefix | Distinguishes logs of several listeners; empty for none |
| Split by Source Device | Do Not Split (one log), Create Log by Unique IP/Host Name (<prefix> <source>), Create Log by IP Mask (<prefix> <mask>) |
| Message JSON Key, Split by JSON Columns | The message field, and a list of JSON keys separated by -> that build the log path and name (append * to mark the host key) |
| Listener Data Location | Where received data is stored; the data directory by default |
| Indexing Node, Indexing Interval | In a cluster, which node indexes and how often |
| JSON Parsing Level | How deep JSON is extracted into columns |
Received data is stored under the parent folder and is available for search, reports and alerts.
Shippers that use it
- Fluent Bit — the
httpoutput withtls On, the host and port of the listener and the URI/logeye/api/logger.jsp?token=<token>&hostName=<host>; Windows service or Linux package, DaemonSet or sidecar on Kubernetes and Tanzu. - Logstash — the
httpoutput withformat => "json",http_method => "post"and the listener URL including the token; the filter addsxpologPath,xpologNameandxpologTypeper file. - Anything that can POST JSON. For syslog, NetFlow and Kafka sources see Sources and the listeners reference.
Next: Configuration API
Source: XPLG wiki, pages 1598685520, 1595637847, 3151659026, 2053865492, 1919418369, 1599143870, 2398388225, 1594131316 (https://xpolog.atlassian.net/wiki/spaces/XPOL/pages/1598685520). Pending from XPLG engineering: payload limits, batching and throttling of the HTTP/S listener.
