Ports and the effective port

The root receiver prefers port 14317 for gRPC and port 14318 for HTTP. It does not use the standard collector ports 4317 and 4318, because a Docker port forward or another collector often holds those.

What happens when a port is busy

When another process holds 14317 or 14318, the root moves along a fixed ladder. The ladder adds 10000, then 20000, to the busy port.

Preferred	Second try	Third try
14317	24317	34317
14318	24318	34318

The ladder gives the same port at every launch, so a config that you write once keeps working. When every ladder port is busy too, the root takes a port from the operating system. That port changes at each launch.

Copy the effective port

Do not assume 14317. Open Collectors → Local OTLP receiver → Connection and copy the port the app shows now. That is the effective port.

Read the port with a tool

The engine reports the ports through its health endpoint. The fields otlpGrpcPort and otlpHttpPort hold the effective ports. The flags otlpGrpcPortConflict and otlpHttpPortConflict are true after a move.

{"healthy":true,"otlpGrpcPort":14317,"otlpHttpPort":14318,
 "otlpGrpcConfiguredPort":14317,"otlpHttpConfiguredPort":14318,
 "otlpGrpcPortConflict":false,"otlpHttpPortConflict":false}

See HTTP API for how to reach the endpoint.

Find what holds the port

Open Terminal and run this command. It lists the process on each of the two ports.

lsof -nP -iTCP -sTCP:LISTEN | grep -E ':(14317|14318) '

Quit that process, or keep it and use the effective port. Both work.