HomeGuidesChangelog
Guides

API Endpoints

Suggest Edits

Checking Sidecar Status - /health

Use the health check endpoint to check the status of the sidecar without running through envelopes. It takes no arguments and returns a JSON response, along with a transparent HTTP status code to indicate the sidecar’s status.

$ curl -v localhost:3000/health
*   Trying 127.0.0.1...
* TCP_NODELAY set
* Connected to localhost (127.0.0.1) port 5000 (#0)
> GET /health HTTP/1.1
> Host: localhost:5000
> User-Agent: curl/7.64.1
> Accept: */*
>
< HTTP/1.1 200 OK
< Content-Type: application/json
< Content-Length: 49
<
* Connection #0 to host localhost left intact
{"last_successful_authentication":0,"keys_ttl":0}* Closing connection 0
  • 200 (OK) indicates that the sidecar is authorized and ready to accept /map requests.
  • 503 (Service Unavailable) indicates that the sidecar has started, but has not yet successfully completed its initial authorization routine. Under normal operation, a sidecar should never stay in this state for an extended period of time. Seeing this code for an extended period could indicate that the sidecar is unable to reach LiveRamp servers. In this case, please contact LiveRamp.
  • 401 (Unauthorized) indicates that the sidecar has contacted LiveRamp, but LiveRamp has denied the request for keys. A sidecar may go into this state during the course of operation if LiveRamp revokes authorization remotely, or if the container loses connectivity and the authorization times out.

last_successful_authentication is a UNIX timestamp in seconds of the last time LiveRamp re-authorized the sidecar instance.

keys_ttl is a UNIX timestamp in seconds of when the current authorization will expire -- it will be equivalent to the last_successful_authentication + four hours.

Creating IDL Mappings - /map

Use /map, the primary IDL mapper endpoint to convert Envelopes to IdentityLinks. It accepts two parameters: a required “env=[envelope identifier]” parameter and an optional “sid=[seat ID]” parameter that can refer to a single seat, or repeat for multiple seats. The /map endpoint returns a JSON-encoded key-value paring of Seat ID to IdentityLink.
If “sid” parameters are used, only the provided Seat IDs and associated IdentityLinks will be included in the output. If no "sid" parameter is included, the endpoint returns IdentityLinks for all available seats the sidecar is authorized for.

$ curl -vv \
> 'localhost:3000/map?env=AjfowUURXDJnQmc_HNeuswelMv4ZHZQJFM8TpiUnYEyA81Vdgg&sid=SEAT0046&sid=SEAT0002'
*   Trying ::1...
* TCP_NODELAY set
* Connected to localhost (::1) port 3000 (#0)
> GET /map?env=AjfowUURXDJnQmc_HNeuswelMv4ZHZQJFM8TpiUnYEyA81Vdgg&sid=SEAT0046&sid=SEAT0002 HTTP/1.1
> Host: localhost:3000
> User-Agent: curl/7.54.0
> Accept: */*
>
< HTTP/1.1 200 OK
< Content-Type: application/json
< Date: Tue, 23 Oct 2018 00:53:06 GMT
< Content-Length: 127
<
* Connection #0 to host localhost left intact
{"SEAT0002":"Xm00024Bro9-lyzK0Ng_pBKVu5el_q8yKVRMW40TDbmTAlpMs","SEAT0046":"Xm004664X0YqsNhpa0JFxtwQLboMVcrihTjuiPp8nvQ2dqEYs"}

The /map endpoint is intended to always return a quick response, even in the event the sidecar becomes unauthorized. There is no need to query the /health endpoint prior to each /map request. Note that /map will not follow the 503 behavior on startup; it will always return either a 200, 204, 401 or 410 status code.

  • 200 indicates a successful lookup.
  • 204 indicates that the envelope contained data not authorized for certain partners
  • 401 is a sign that there was a problem with authenticating the Sidecar -- sustained 401 responses may signal a need to restart the Sidecar and check that it is able to reach the check-in service.
  • 410 is returned when an envelope has expired -- check your envelope source and reduce any caching.
  • 500 (Internal Server Error) status code will be thrown if something unexpected goes wrong within the Sidecar, but this is unexpected behavior. We recommend documenting requests that cause this behavior and reporting them to LiveRamp. The sidecar will report telemetry on such failures back to LiveRamp for production sidecar builds.

In a production environment, Seat IDs will be provided by the SSP and mapped to IdentityLink encodings by LiveRamp. To add new mapping or change existing seat IDs, contact LiveRamp Product Operations.

Monitoring Sidecar - /metrics

You can check to see how much data a sidecar instance is processing (and at what internal latency) by calling the /metrics API endpoint. 

$ curl localhost:5000/metrics 
{
  "map_latency_50_percentile": 116300,
  "map_latency_90_percentile": 181400,
  "map_latency_99_percentile": 1.56745e+06,
  "query_count": 3779,
  "bad_request_count": 0
}

This will return the number of requests processed, the subset which were bad requests and latency (measured in nanoseconds) at various percentiles.

Adding /prometheus will return the metrics in Prometheus metric format: 

$ curl localhost:3000/metrics/prometheus
# HELP bad_request_count Number of bad requests per minute
# TYPE bad_request_count gauge
bad_request_count 0
# HELP map_latency_50_percentile 50th percentile latency number
# TYPE map_latency_50_percentile gauge
map_latency_50_percentile 114400
# HELP map_latency_90_percentile 90th percentile latency number
# TYPE map_latency_90_percentile gauge
map_latency_90_percentile 180800
# HELP map_latency_99_percentile 99th percentile latency number
# TYPE map_latency_99_percentile gauge
map_latency_99_percentile 937850
# HELP query_count Number of queries processed in a minute
# TYPE query_count gauge
query_count 3642

Updated almost 6 years ago