Skip to main content

Integrate an application

Production publishers should connect directly to the Unix socket, keep the connection open, and reconnect with backoff after an agent restart. Do not launch constellation-agent emit for every sample.

Discover the socket​

Read the installed path rather than hardcoding it:

. /etc/constellation/socket.env
echo "$CONSTELLATION_SOCKET_PATH"

The default is /run/constellation-agent/telemetry.sock.

Write a stream​

The application contract is:

  1. Connect with AF_UNIX and SOCK_STREAM.
  2. Write one line-protocol metric per line.
  3. Include a non-empty entity_id tag and at least one field.
  4. Reuse the connection.
  5. Reconnect with bounded backoff when the connection closes.
  6. Treat a completed write as local handoff, not remote acknowledgement.
ground_station,entity_id=GS-001 lat=34.2,lon=-118.2,snr=12.7 1785528000000000000

The timestamp is optional Unix nanoseconds. Omit it when Fleet Agent arrival time is an acceptable observation time.

Before interpolating arbitrary identifiers or values, implement the escaping and type rules in Protocol reference. Its reference encoder and connection-reuse section are the source of truth.

Acceptance checklist​

  • Run the publisher under its dedicated service account.
  • Confirm group membership after the process starts.
  • Test an agent restart while the publisher is connected.
  • Test a network outage and confirm buffered data drains after recovery.
  • Run sudo constellation-agent verify independently of application health.
  • Use sudo constellation-agent debug on briefly to inspect integration traffic, then turn it off.

Next: Equipment contracts: ACU and modem.