Ping

Services

PingService Service

Connectivity testing service for GoodMem inference resources.

Auth: gRPC metadata authorization: Bearer <api-key>. Permissions:

PING_EMBEDDER_OWN or PING_EMBEDDER_ANY for embedder targets
PING_RERANKER_OWN or PING_RERANKER_ANY for reranker targets
PING_LLM_OWN or PING_LLM_ANY for LLM targets

Global Errors: All RPCs may return DEADLINE_EXCEEDED, CANCELLED, UNAVAILABLE, RESOURCE_EXHAUSTED, INTERNAL.

Ping

Summary: Opens a bidirectional ping session. Clients send an initial configuration followed by optional control messages; the server streams probe results and a final summary.

	Type
Request	`stream goodmem.v1.PingClientMessage`
Response	`stream goodmem.v1.PingServerMessage`

Auth: gRPC metadata authorization: Bearer <api-key>. Permissions Required: PING_* matching the resolved target type (*_OWN for owned targets, *_ANY to access any tenant). Request: The first client message MUST be PingConfig; optional PingControl messages may follow to pause/resume/cancel the session. No other message types are accepted. Response: Stream of PingResult events for each completed probe, optional PingNotice diagnostics, and a terminal PingSummary when the session finishes. Side Effects: Generates real traffic against the target provider (may incur billable calls). Idempotency: Session based; retry by opening a new stream. Error Codes:

UNAUTHENTICATED: Missing/invalid API key metadata
PERMISSION_DENIED: Caller lacks the required PING_* permission
INVALID_ARGUMENT: First message not PingConfig, malformed target ID, conflicting payload
FAILED_PRECONDITION: Target exists but is disabled/unavailable Examples: Use a gRPC SDK for interactive streaming; PingOnce below provides a unary reference flow.

PingOnce

Summary: Performs a single probe using the supplied configuration and returns the result.

	Type
Request	`goodmem.v1.PingOnceRequest`
Response	`goodmem.v1.PingResult`

Auth: gRPC metadata authorization: Bearer <api-key>. Permissions Required: Same PING_* requirements as Ping. Request: PingOnceRequest containing the target and optional payload overrides. Response: One PingResult describing the probe outcome. Side Effects: One provider call matching the supplied configuration. Idempotency: Non-idempotent; repeated calls create new probes. Error Codes:

UNAUTHENTICATED: Missing/invalid API key metadata
PERMISSION_DENIED: Caller lacks the required PING_* permission
INVALID_ARGUMENT: Malformed target ID, unsupported payload selection, timeout < 1 ms
NOT_FOUND: Target resource not found
FAILED_PRECONDITION: Target exists but is disabled or misconfigured
INTERNAL: Unexpected provider or server failure Examples:

grpcurl -plaintext \
-H 'authorization: Bearer ${GOODMEM_API_KEY}' \
-d '{
"target_id": "BASE64_UUID_BYTES",
"target_type_hint": "TARGET_TYPE_EMBEDDER"
}' \
localhost:9090 goodmem.v1.PingService/PingOnce

Messages

PingClientMessage

Client-to-server envelope for Ping. The first message MUST be config.

Field	Type	Description
`config`	`goodmem.v1.PingConfig`
`control`	`goodmem.v1.PingControl`

PingServerMessage

Server-to-client envelope for Ping responses.

Field	Type	Description
`result`	`goodmem.v1.PingResult`
`summary`	`goodmem.v1.PingSummary`
`notice`	`goodmem.v1.PingNotice`

PingConfig

Configuration for a ping session.

Field	Type	Description
`target_id`	`bytes`	Target resource identifier (UUID, 16 bytes).
`target_type_hint`	`goodmem.v1.TargetType`	Optional hint about the expected resource type; used for permission checks.
`count`	`uint32`	Number of probes to run (default 4 when unset). Must be ≥1.
`interval_ms`	`uint32`	Delay between probes in milliseconds (default 1000). Must be ≥1.
`timeout_ms`	`uint32`	Per-probe timeout in milliseconds (default 5000). Must be ≥1.
`payload_type`	`goodmem.v1.PayloadType`	Desired payload format. A provider-specific default is used when unspecified.
`payload`	`bytes`	Explicit payload to send with each probe (binary-safe).
`payload_size_bytes`	`uint32`	Generate a synthetic payload with the requested size in bytes.
`max_in_flight`	`uint32`	Maximum concurrent probes (default 1). Values ≥1 enable pipelined probes.
`jitter`	`bool`	When true, adds ≤5% random jitter to probe scheduling to avoid alignment effects.
`labels`	`...dmem.v1.PingConfig.LabelsEntry`	Arbitrary labels echoed in `PingResult.metadata` and summaries.

PingConfig.LabelsEntry

Field	Type	Description
`key`	`string`
`value`	`string`

PingControl

Control message for an active ping session.

Field	Type	Description
`action`	`goodmem.v1.PingControl.Action`	Operation to perform.

PingResult

Result from an individual probe.

Field	Type	Description
`endpoint`	`goodmem.v1.EndpointInfo`	Resolved endpoint metadata for the target being probed.
`seq`	`uint32`	Sequential probe number (1-based).
`bytes_sent`	`uint32`	Payload bytes transmitted.
`bytes_received`	`uint32`	Payload bytes received.
`ok`	`bool`	True when the provider responded successfully within the timeout.
`http_status`	`uint32`	Provider HTTP status code or equivalent transport status.
`error_message`	`string`	Human-readable description when `ok` is false.
`rtt_ms`	`double`	Observed round-trip latency in milliseconds.
`timing`	`goodmem.v1.PingTiming`	Raw timing data recorded on the server.
`metadata`	`...em.v1.PingResult.MetadataEntry`	Additional provider metadata (request IDs, throttling signals, etc.).

PingResult.MetadataEntry

Field	Type	Description
`key`	`string`
`value`	`string`

PingSummary

Summary emitted at the end of a ping session.

Field	Type	Description
`endpoint`	`goodmem.v1.EndpointInfo`	Endpoint metadata copied from the final probe.
`requests`	`uint32`	Total number of probes scheduled.
`responses`	`uint32`	Number of responses received (including timeouts/errors).
`ok`	`uint32`	Count of probes that succeeded.
`timeouts`	`uint32`	Count of probes that exceeded the timeout.
`errors`	`uint32`	Count of probes that failed for other reasons.
`rtt_min_ms`	`double`	Minimum observed round-trip latency (ms).
`rtt_avg_ms`	`double`	Average observed round-trip latency (ms).
`rtt_p50_ms`	`double`	Median (p50) round-trip latency (ms).
`rtt_p90_ms`	`double`	90th percentile round-trip latency (ms).
`rtt_p99_ms`	`double`	99th percentile round-trip latency (ms).
`rtt_max_ms`	`double`	Maximum observed round-trip latency (ms).
`requests_per_second`	`double`	Effective request throughput across the session.
`bytes_per_second`	`double`	Aggregate bytes per second (send + receive).
`applied_limits`	`...PingSummary.AppliedLimitsEntry`	Resource limits applied by the server (count clamps, payload clamps, etc.).

PingSummary.AppliedLimitsEntry

Field	Type	Description
`key`	`string`
`value`	`string`

PingNotice

Non-fatal notices sent while a ping session is active.

Field	Type	Description
`code`	`string`	Machine-readable notice identifier (for example `COUNT_CLAMPED`).
`message`	`string`	Human-readable description of the notice.
`details`	`...mem.v1.PingNotice.DetailsEntry`	Additional contextual detail (limits applied, provider hints, etc.).

PingNotice.DetailsEntry

Field	Type	Description
`key`	`string`
`value`	`string`

PingTiming

Timing information captured during a probe.

Field	Type	Description
`client_send_time_unix_nanos`	`int64`	When the client dispatched the probe request (Unix epoch nanoseconds).
`server_received_time_unix_nanos`	`int64`	When the GoodMem server received the probe (Unix epoch nanoseconds).
`server_send_time_unix_nanos`	`int64`	When the GoodMem server sent the probe response (Unix epoch nanoseconds).
`client_receive_time_unix_nanos`	`int64`	When the client consumed the probe response (Unix epoch nanoseconds).

PingOnceRequest

Convenience request for PingService.PingOnce.

Field	Type	Description
`target_id`	`bytes`	Target resource identifier (UUID, 16 bytes).
`target_type_hint`	`goodmem.v1.TargetType`	Optional hint about the expected resource type.
`payload_type`	`goodmem.v1.PayloadType`	Desired payload type (defaults to provider-specific value).
`payload`	`bytes`
`payload_size_bytes`	`uint32`
`timeout_ms`	`uint32`	Per-probe timeout in milliseconds (default 5000). Must be ≥1.

EndpointInfo

Resolved endpoint metadata returned with each result.

Field	Type	Description
`target_type`	`goodmem.v1.TargetType`	Resolved resource classification.
`target_id`	`bytes`	UUID (bytes) of the resource that was pinged.
`resolved_endpoint`	`string`	Fully resolved endpoint that the server contacted.
`provider`	`string`	Provider name backing the resource (for example `OPENAI`, `VLLM`).
`model_identifier`	`string`	Provider-specific model identifier used for the probe.

Enums

PingControl.Action

Actions that can be applied to the active session. Currently informational only.

Name	Value	Description
`ACTION_UNSPECIFIED`	0
`ACTION_PAUSE`	1
`ACTION_RESUME`	2
`ACTION_CANCEL`	3

TargetType

Supported resource categories for ping operations.

Name	Value	Description
`TARGET_TYPE_UNSPECIFIED`	0
`TARGET_TYPE_EMBEDDER`	1
`TARGET_TYPE_RERANKER`	2
`TARGET_TYPE_LLM`	3

PayloadType

Supported payload formats.

Name	Value	Description
`PAYLOAD_TYPE_UNSPECIFIED`	0	Default behaviour. Emits a target-specific plain-text payload.
`PAYLOAD_TYPE_TEXT`	1	Plain UTF-8 text payload (mirrors the default but honours requested sizes).
`PAYLOAD_TYPE_JSON`	2	Fixed JSON document payload (`{"ping":true}`).
`PAYLOAD_TYPE_BINARY`	3	Binary payloads are currently unsupported and produce `INVALID_ARGUMENT`.

Ping

On this page