Event Logging
Interfaces
Inbound contract and failure model for Event Logging
Protocol
- Connect Protocol (JSON) over HTTP/2 / h2c.
- Unary route:
/events.v1.EventLoggingService/LogEvent - Service definition:
proto/events/v1/events.proto
Authentication
- Internal ingress only. Cloud Run IAM is the auth boundary.
- Callers need
roles/run.invokeron the deployed service. - The app records platform-provided caller identity from
x-goog-authenticated-user-emailandx-goog-authenticated-user-idinto service-managed audit metadata. - The app does not perform a second bearer-token validation pass.
RPC catalog
| RPC | Direction | Auth | Notes |
|---|---|---|---|
LogEvent | Unary | Required | Persist one event row and optionally forward it to Statsig. |
LogEvent request contract
| Field | Required | Semantics |
|---|---|---|
event_name | Yes | Stable platform event name. Blank values are rejected. |
event_type | No | Caller-supplied event classification. Persisted to the event_type column when present. |
actor_id | No | Caller-supplied actor identifier. Persisted to the actor_id column when present. |
metadata | No | Arbitrary nested JSON, capped at 256 top-level keys and 64 KiB serialized size. |
event_ts | No | Logical occurrence time. Defaults to current UTC when omitted. |
idempotency_key | No | Correlation token only. Presence does not guarantee deduplication. |
forward_to_statsig | No | Defaults to true when omitted. Set to false for Spanner-only writes. |
Additional rules:
- Callers never send
event_id; the service generates it. _eventLogis reserved for service-managed metadata and is rejected if sent by a caller.- Retries can create duplicate rows because v1 does not deduplicate on
idempotency_key.
Response contract
| Field | Present when | Notes |
|---|---|---|
event_id | Full success | Generated by the service and persisted as the row key. |
idempotency_key | Caller supplied a non-blank key and the RPC fully succeeded | Echoed for correlation. |
Error model
| Condition | Connect code | Notes |
|---|---|---|
| Proto validation or normalization failure | INVALID_ARGUMENT | Includes blank event_name, blank event_type or actor_id when supplied, reserved _eventLog, or oversized metadata. |
| Spanner write failure | INTERNAL | No Statsig forwarding is attempted. |
| Statsig forward failure after a successful write | UNAVAILABLE | The event row is already stored, so retries may create duplicates. |
Failure-after-write behavior
The service writes to Spanner before forwarding to Statsig. That means
UNAVAILABLE does not imply "nothing was written." It specifically means "the
write succeeded, but the downstream Statsig side effect failed."
Last updated on