Skip to main content

Configuring a Praxis Gateway collector

Setting up a Praxis Gateway involves configuring two Praxis pipelines:

  1. The Praxis Gateway pipeline on the praxis-collector that acts as the aggregation point: at least one ingress, usually the OTLP Source (Praxis’s standard collector-to-collector listener), and optionally Syslog, TCP, UDP, or others — see Overview.
  2. The other Praxis collectors that export to the Praxis Gateway collector using the OTLP Destination (same component as in any installation without a Praxis Gateway), instead of sending telemetry directly to each export destination (for example SecOps, object storage, or another OTLP hop) without an aggregation tier. The Praxis management plane is where you define that graph; it is not a pipeline destination for bulk telemetry. Third-party agents that speak OTLP can target the same Praxis Gateway collector OTLP source; their exporter configuration is interoperability, not the primary Praxis path.

This page walks through both sides, then TLS. For creating PEM files and mTLS rollout order, see TLS and certificates.

note

The Praxis Gateway collector runs on the same praxis-collector you install anywhere else. Follow the Kubernetes install guide (or your platform's install process) to provision the supervisor, then configure its pipeline in the Praxis management plane as described below.

Prerequisites​

  • An installed praxis-collector that will act as the Praxis Gateway collector. It must be reachable from every other Praxis collector (and any OTLP client you allow) on the network. For telemetry export, the Praxis Gateway collector is often the place that opens outbound to your data destinations (for example SecOps, GCS, object storage). Collectors also use the Praxis management plane for pipeline configuration and insights (and typically OpAMP); that is separate from the export destinations you attach in the pipeline graph—the management plane is not a destination for bulk pipeline export in the same way SecOps or storage are.
  • A dedicated Praxis Gateway pipeline in the Praxis management plane for that host.
  • Network between other Praxis collectors and the Praxis Gateway collector allowed on the chosen port (commonly 4317 for gRPC and 4318 for HTTP).
  • (Optional, for TLS) A TLS certificate and private key for the Praxis Gateway collector's hostname or IP, plus a CA bundle that those Praxis collectors can trust.

Step 1 — Configure the Praxis Gateway pipeline​

On the Praxis Gateway collector, build a pipeline in the Praxis management plane whose primary ingress for other Praxis collectors is the OTLP Source — the same source type as any receiver; the Praxis Gateway role is where you run it, not a different product.

You can add more than one source on the same Praxis Gateway pipeline — for example OTLP (Praxis and optional OTLP-compatible senders) plus Syslog, TCP, or UDP — when you want one host to aggregate syslog, raw TCP/UDP, and Praxis-to-Praxis OTLP before a single export path.

Required Parameters​

ParameterTypeDescription
Credential TypestringRequired. Pick Noauth for an open endpoint on a trusted network or BearerTokenAuth to require a shared token from every client (every Praxis collector or other OTLP sender you authorize).
enable_grpcboolSet to true if you want gRPC (recommended for high throughput for Praxis and most OTLP clients).
grpc_endpointstringAddress and port the Praxis Gateway collector binds to for gRPC. Use 0.0.0.0:4317 so it listens on all interfaces; the Praxis Gateway collector hostname is what sending Praxis collectors use in their OTLP destination.
enable_httpboolSet to true if you also want to accept OTLP over HTTP.
http_endpointstringAddress and port the Praxis Gateway collector binds to for HTTP. Typically 0.0.0.0:4318.

You must enable at least one of gRPC or HTTP. You can enable both — each Praxis OTLP destination (or other OTLP client) uses whichever protocol it supports.

Destinations​

Add any export destinations the Praxis Gateway pipeline should send telemetry to: for example Google SecOps, GCS, object storage, an OTLP hop to another system, and so on. (You add and manage these in the Praxis management plane; the management plane is for configuration and insights, not a bulk telemetry sink in the pipeline graph.) The Praxis Gateway collector is often where egress from your network to those destinations is concentrated.

Processors (optional)​

You can place processors after all sources and before destinations on the Praxis Gateway to apply common logic in one place (for example: batching, masking, enrichment with k8s_attributes, or filtering). This is a common reason to use a Praxis Gateway — it lets you enforce policy once on every ingress path (OTLP, syslog, TCP, UDP, and so on).

Minimal non-TLS OTLP source example (Praxis Gateway)​

This is the OTLP Source configuration for a Praxis Gateway that listens on gRPC and HTTP without TLS. Only use this when the path between the Praxis Gateway collector and other Praxis collectors (and any other OTLP clients) is trusted.

{
  "enable_grpc": true,
  "grpc_endpoint": "0.0.0.0:4317",

  "enable_http": true,
  "http_endpoint": "0.0.0.0:4318",

  "grpc_tls": {
    "enabled": false
  },
  "http_tls": {
    "enabled": false
  }
}
warning

A non-TLS Praxis Gateway OTLP receiver accepts telemetry from anyone who can reach its ports. Only use it on networks you fully control (a private VPC, a VPN, a K8s internal service, etc.) and restrict ingress with firewall rules or security groups to the CIDRs where your sending Praxis collectors run.

Step 2 — Point other Praxis collectors at the Praxis Gateway collector​

On every Praxis collector that should forward through the Praxis Gateway collector, set the pipeline’s export step to the OTLP Destination aimed at the Praxis Gateway collector’s OTLP Source (host, port, TLS, and auth as you configured in Step 1). This is the same destination node you use for any Praxis-to-Praxis or Praxis-to-destination OTLP hop; the Praxis Gateway pattern only changes the target address to the Praxis Gateway collector.

See the OTLP Destination reference for the full field list. For the Praxis Gateway use case, the important fields are:

Required Parameters​

ParameterTypeDescription
Credential TypestringRequired. Use Noauth to match a Noauth Praxis Gateway collector, or configure credentials that match its authentication mode.
protocolstringgrpc or http. Must match something the Praxis Gateway collector has enabled.
grpc_endpointstringPraxis Gateway collector address for gRPC — e.g. gateway.internal:4317. No scheme for gRPC.
http_endpointstringPraxis Gateway collector address for HTTP — http://gateway.internal:4318 when TLS is off, https://gateway.internal:4318 when TLS is on.
grpc_tls.enabled / http_tls.enabledboolMust match the Praxis Gateway collector's TLS state.
grpc_tls.insecure / http_tls.insecurebooltrue disables server-certificate verification. Keep false in production and supply a CA.
note

Praxis uses the built-in OTLP Destination above. If you also send from a non-Praxis process, configure its OTLP exporter to the same host, ports, and TLS; the following subsection shows a common OpenTelemetry Collector example for comparison only.

Minimal non-TLS Praxis destination (sending to the Praxis Gateway collector)​

Use only on a trusted internal network. Keep grpc_tls.enabled false. Do not set insecure: true together with enabled: true on TLS (that turns off certificate verification while still using TLS).

{
  "protocol": "grpc",
  "grpc_endpoint": "gateway.internal:4317",

  "grpc_tls": {
    "enabled": false
  }
}

OpenTelemetry Collector (optional interoperability)​

OpenTelemetry Collector (not Praxis) uses its own otlp exporter; plaintext to a lab Praxis Gateway collector is often tls.insecure: true (see upstream docs). Example:

exporters:
  otlp:
    endpoint: gateway.internal:4317
    tls:
      insecure: true

Step 3 — Enable TLS (recommended for production)​

TLS on the hop between other Praxis collectors and the Praxis Gateway collector gives you:

  • Encryption — payloads are not readable on the wire.
  • Server authentication — clients verify the Praxis Gateway collector’s certificate (one-way TLS).
  • Optional mTLS — the Praxis Gateway collector requests a client certificate and verifies it against a client CA, so only collectors with issued certs can connect.

:::info Paths are yours to choose

Configuration fields such as cert_file, key_file, ca_file, and client_ca_file are absolute paths on the host (or paths inside a container mount). There is no required directory name. Pick a location your OS and security standards allow (for example a dedicated mount under /etc/... on Linux, or a Kubernetes Secret volume path) and use the same string in the Praxis management plane.

Throughout the examples below, <TLS_DIRECTORY> is a placeholder — replace it with your real directory on that machine.

:::

For how to create CA, server, and client PEM files with OpenSSL, rollout order for mTLS, and openssl s_client checks, see TLS and certificates. If your organization already documents PKI (Vault, AD CS, public CA), follow that guide for PEM issuance and still use the field mapping below.

Certificates you need​

ArtifactWhere it typically livesPurpose
Server cert + keyPraxis Gateway collector host onlyPraxis Gateway collector proves its identity to TLS clients.
CA bundle (ca_file on clients)Every Praxis collector that sends to the Praxis Gateway collector (or other OTLP client)Clients verify the Praxis Gateway collector's server cert chains to this trust anchor.
Client cert + key (mTLS)Every such Praxis collector (or per-host certs)Collectors prove identity when the Praxis Gateway collector requests a client cert.
Client CA (client_ca_file on Praxis Gateway collector)Praxis Gateway collector host onlyPraxis Gateway collector verifies incoming client certificates.

The server certificate’s Subject Alternative Names (SANs) must include whatever hostname or IP clients use in grpc_endpoint / http_endpoint. IP-only clients need an IP SAN on the server cert.

Praxis Gateway collector: OTLP source with TLS (gRPC + HTTP)​

Use distinct filenames if you want (for example gateway.crt / gateway.key); only the absolute paths in config must match where files were installed.

{
  "enable_grpc": true,
  "grpc_endpoint": "0.0.0.0:4317",

  "enable_http": true,
  "http_endpoint": "0.0.0.0:4318",

  "grpc_tls": {
    "enabled": true,
    "min_version": "1.2",
    "cert_file": "<TLS_DIRECTORY>/gateway-server.crt",
    "key_file": "<TLS_DIRECTORY>/gateway-server.key",
    // mTLS — set to the public CA that signed your *client* certificates:
    // "client_ca_file": "<TLS_DIRECTORY>/ca.crt"
  },

  "http_tls": {
    "enabled": true,
    "min_version": "1.2",
    "cert_file": "<TLS_DIRECTORY>/gateway-server.crt",
    "key_file": "<TLS_DIRECTORY>/gateway-server.key",
    // "client_ca_file": "<TLS_DIRECTORY>/ca.crt"
  }
}

The private key file must be readable only by the user the collector runs as (for example mode 600). On Kubernetes, mount PEMs from a Secret and set paths to the mount directory.

Praxis collector destination with TLS (OTLP to the Praxis Gateway collector)​

{
  "protocol": "grpc",
  "grpc_endpoint": "gateway.internal:4317",

  "grpc_tls": {
    "enabled": true,
    "insecure": false,
    "min_version": "1.2",
    "ca_file": "<TLS_DIRECTORY>/ca.crt",
    // mTLS — same paths on each host after you copy client.pem material:
    // "cert_file": "<TLS_DIRECTORY>/client.crt",
    // "key_file": "<TLS_DIRECTORY>/client.key"
  }
}

OpenTelemetry Collector export to the same Praxis Gateway collector (for comparison; Praxis clients use the JSON above):

exporters:
  otlp:
    endpoint: gateway.internal:4317
    tls:
      ca_file: "<TLS_DIRECTORY>/ca.crt"
      # mTLS:
      # cert_file: "<TLS_DIRECTORY>/client.crt"
      # key_file: "<TLS_DIRECTORY>/client.key"

TLS quick rules​

  • With grpc_tls.enabled / http_tls.enabled set to true, keep insecure on clients set to false and always supply a ca_file you trust.
  • min_version: "1.2" is a reasonable floor; TLS 1.3 is used when both sides support it.
  • Renewing the Praxis Gateway collector's server cert signed by the same CA usually does not require collector config changes if ca_file still validates the new chain.
  • When rotating the CA, update ca_file on all clients and client_ca_file on the Praxis Gateway collector (if used) before retiring the old issuer.

Step 4 — Optional: Bearer Token Authentication​

Even inside a private network, you may want to require every incoming request to carry a shared token. This is useful when the Praxis Gateway collector is shared across teams and you want a simple way to attribute or revoke access.

On the Praxis Gateway collector OTLP Source, set Credential Type to BearerTokenAuth and configure the token value in the Praxis management plane.

On each Praxis collector that sends to the Praxis Gateway collector, set its OTLP Destination Credential Type accordingly and inject the same token as a header via grpc_headers / http_headers. Other OTLP clients use their own header or extension mechanism for the same token.

// Praxis collector — OTLP Destination with bearer token
{
  "protocol": "grpc",
  "grpc_endpoint": "gateway.internal:4317",
  "grpc_headers": {
    "authorization": "Bearer <shared-token>"
  },
  "grpc_tls": {
    "enabled": true,
    "insecure": false,
    "ca_file": "<TLS_DIRECTORY>/ca.crt"
  }
}
warning

Treat the bearer token like any other credential. Store it in a secret store (Kubernetes Secret, Vault, etc.), not in a plain ConfigMap or shell history. Rotate it whenever a host with the token is decommissioned.

Verifying the Setup​

After applying the pipeline on the Praxis Gateway collector and updating one Praxis collector to point at it:

  1. Check the Praxis Gateway collector is listening. 
    ss -ltnp | grep -E '4317|4318'
    # Or, from another host:
    nc -vz gateway.internal 4317
  2. Watch the Praxis Gateway collector logs for accepted connections and exported batches. 
    # Systemd-managed host:
    journalctl -u praxis-collector -f
    # Kubernetes:
    kubectl logs -n praxis-collector -l app.kubernetes.io/component=supervisor -f
  3. Watch the sending Praxis collector logs for successful OTLP exports. Failures typically report TLS handshake errors or connection refused, which are the fastest signals that the endpoint, certificate, or firewall is misconfigured.
  4. Confirm telemetry reaches your export destinations (for example in Google SecOps or object storage you configured). The Praxis management plane is where you check pipeline status and insights; it is not a data sink in the same sense as SecOps or GCS. If the Praxis Gateway collector receives data but nothing arrives at export destinations, the problem is usually egress from the Praxis Gateway collector to a configured destination, not the OTLP path from sending collectors to the Praxis Gateway collector.

Common Pitfalls​

SymptomLikely Cause
connection refused on a Praxis collectorThe Praxis Gateway collector isn't listening on that port or a firewall is dropping the packets.
x509: certificate signed by unknown authorityca_file on the client does not include the CA that signed the Praxis Gateway collector's server certificate.
x509: certificate is valid for ..., not <hostname>The Praxis Gateway collector's certificate SANs don't include the hostname/IP that the Praxis collectors use.
Unauthenticated / 401 responsesBearer token mismatch, or the Praxis Gateway collector uses BearerTokenAuth but a Praxis collector is configured as Noauth.
Works over http:// but fails over https://TLS disabled on the Praxis Gateway collector's HTTP receiver, or enabled on the receiver but the client still uses the http scheme.
Praxis Gateway collector receives data, nothing arrives downstreamA configured export destination (for example SecOps, GCS, or an OTLP export to another system) is wrong or the Praxis Gateway collector host cannot reach it. The Praxis management plane is for configuration and insights—it is not the downstream telemetry sink. Check Praxis Gateway collector logs and egress (firewall, DNS) to the real destination in the pipeline.

Multi-protocol ingress: syslog, TCP, UDP, and forwarders​

The Praxis Gateway collector is not limited to OTLP from other Praxis collectors. The same Praxis pipeline can expose native Praxis sources for other ecosystems:

SourceTypical sendersPractical use on a Praxis Gateway
OTLPPraxis collectors (first-class), optional OpenTelemetry-compatible senders, Fluent Bit OpenTelemetry outputStandard Praxis path: collector-to-collector and OTLP-shaped telemetry.
SyslogFirewalls, switches, routers, load balancers, printers, hypervisors, legacy Linux servicesCentral syslog aggregation inside a VPC; one IP/DNS and port range to allow; parse and mask once before export.
TCPCustom agents, log shippers speaking line-delimited JSON or framed payloadsGeneric log receiver when a vendor only offers “TCP JSON” or similar.
UDPHigh-volume fire-and-forget telemetry, some appliancesHigh-throughput ingress where loss is acceptable or handled upstream; pair with sampling on the Praxis Gateway if needed.

Fluent Bit — OpenTelemetry output to the Praxis Gateway collector’s OTLP gRPC or HTTP endpoint (match host, port, TLS, and auth to the Praxis OTLP Source). This is an add-on path; Praxis-to-Praxis traffic uses the same listener.

Fluentd — no single global standard; common patterns are HTTP to an HTTP-capable receiver where supported, syslog to the Praxis Gateway collector's Syslog source, or OpenTelemetry Collector beside Fluentd with OTLP to the Praxis Gateway collector. Pick the path that matches your Praxis sources and security controls.

OpenTelemetry Collector — otlp exporter to the Praxis Gateway collector; field semantics align with the Praxis OTLP Destination (CA, optional mTLS).

For every non-OTLP source, still apply network controls (security groups, firewall, iptables, Kubernetes NetworkPolicy) so only expected CIDRs or namespaces can reach the listener ports.

  • TLS and certificates — OpenSSL walkthrough, mTLS rollout order, verification commands.
  • OTLP Source — full reference for every field on the Praxis Gateway collector's receiver.
  • OTLP Destination — full reference for every field Praxis collectors use to export to the Praxis Gateway collector.
  • Kubernetes Install — how to install the underlying praxis-collector that will run the Praxis Gateway pipeline.