Ravensight

Check your integration before and after you ship

Two layers watch your integration. The dashboard computes implementation health from your game's own live traffic, and a public scanner checks your source tree before you ship. Both feed the same card on your game's Overview page.

Live implementation health

Automatic, no setup. The API already sees what your integration does: requests rejected for size, event names exploding in cardinality, payloads brushing the 8KB ceiling, sessions with no end-of-session marker, and reserved rs_ keys with values Ravensight does not know. The Implementation health card on Overview summarizes it over the last 7 days and tells you what to change.

no_game_exited means no session in the window sent game_exited, the marker for the end of a session. It is about the missing marker, not lost delivery: the events in those sessions were stored, and session length is measured to the last stored event. The JavaScript SDK sends game_exited automatically in a browser; the native SDKs send it from their quit and lifecycle hooks; a scripted runner that kills the app never sends it. The finding is info when every session that started also sent events after game_started, and a warning only when some sessions sent nothing at all after the start, which can mean the queue is not flushed before the app closes.

A game with public keys gets a public_keys block on the card: each live key (paused included; revoked and expired keys are history, not health) with its label, prefix, state, accepted events this month, its ceiling if one is set, what remains under it and what its events would cost in blocks, its refusal counts and its most frequent unlisted names. The key list in Settings shows the same signals. Its findings, each with the id public_key:<code>:<prefix>: needs_funds (error: the included allowance is used and the balance cannot buy the next block of events, which stops every key in the account; add funds to keep accepting events), ceiling_reached (error: the key is at its ceiling or has refused a batch at it) and ceiling_near (warning: 80 percent of the ceiling), unlisted_names (note: events refused because their names are not on the allowlist, with the most frequent names, so you can add the ones you meant), rejection_spike (warning: at least 100 refusals this month and at least 20 percent of what the key was sent), origin_mismatch (sessions from origins not on the key's list: a warning while enforcement is off, a note when they were refused), expiring (warning: the key expires within 7 days) and device_concentration (warning: at least 1,000 events under the key and one device id sending at least half of them). Device concentration reads the key's recent sessions, those opened in the last 24 hours that are still alive, and a session ends at its lifetime (one hour by default), so it sees roughly the last session lifetime of traffic, not a full day.

What this data can answer

Below its findings, the Implementation health card lists four questions and says, from this game's own events, whether the data can answer each one. A question it cannot answer comes with a one-line reason that names what to send.

  • Do players come back? (retention) Needs a real event at least 7 days old, so day 7 retention has a cohort old enough to measure.
  • Where do players stop progressing? (levels_funnel) Needs events sent with rs_kind: "level_start" and an end: rs_kind: "level_complete", a terminal event from the detection profile, or, when deaths are outcomes, an event sent with rs_kind: "death". A death matched only by its name does not count here. Without them, a funnel read from event names alone (level_started and level_completed on events that carry a place) still answers, with a note that it is inferred and that rs_kind makes it exact.
  • Which paths do players take between places? (journeys) Needs events that carry a place.
  • How do groups of players differ? (segments) Needs events that carry properties of their own, beyond the reserved rs_ keys and the place keys level, location and track.

In the API answer the block is answerable_questions: a boolean per question, reasons, keyed by each question that is false, and notes, keyed by each question answered only by inference. Two warnings sit beside it on the card, with their own title and detail: uuid_like_place_values, when a game has at least 20 distinct places in the last 7 days and half or more look like generated ids, which split one place into thousands of rows; and synthetic_only_traffic, when every session in the last 7 days was synthetic: Ravensight Playtest personas or a ravensight-doctor --live ping, which every report leaves out by default. Its title counts each kind.

ravensight doctor

A zero-dependency scanner for your project directory. It detects your engine, finds the SDK, and lints the integration statically: event name length and cardinality, oversized inline payloads, missing track calls, and credentials that must never ship inside a game build (an MCP token or a cloud key in your tree is an error; your publishable gt_live ingest key is fine).

Run it

npx ravensight-doctor

# machine readable, with the full inventory
npx ravensight-doctor --json

# your own track wrapper
npx ravensight-doctor --track-fn capture,Analytics.logEvent

# send one test event and confirm it was stored
RAVENSIGHT_INGEST_KEY=gt_live_xxxx \
npx ravensight-doctor --live

# also submit the report to your dashboard
RAVENSIGHT_INGEST_KEY=gt_live_xxxx \
npx ravensight-doctor --report

What it recognised

Every report lists an inventory: each track call it found with its file, line and literal event name (or none when the name is a variable), the distinct event names with counts, the track functions it looked for, and how many ingest keys it found in the project and under test paths. The pretty report prints a summary and --json prints all of it. A track call counts when the name right before .track( is exactly rs, ravensight or Ravensight, with any chain before it, so this.rs.track( counts and analytics.track( does not.

If your game tracks through its own wrapper, name it with --track-fn (comma separated and repeatable) or in a ravensight.config.json in the directory you scan:

{
  "trackFunctions": [
    "capture",
    "Analytics.logEvent",
    { "name": "track_event", "argIndex": 1 }
  ],
  "ignore": ["vendor/", "*.generated.gd"],
  "gitignore": true
}

argIndex says which argument holds the event name. ignore adds .gitignore style patterns, as does --ignore, and the root .gitignore is honoured unless gitignore is false or you pass --no-gitignore. Ingest keys under test and fixture paths are listed but never used for --report or --live.

Status and exit codes

StatusWhen
failAt least one error finding.
inconclusiveThe doctor could not check your events: it found track calls but none names its event with a string literal, or it found an ingest key but no track call it recognises. Name your wrapper with --track-fn to resolve it.
warnAny other warning.
passNo errors or warnings. Only a real pass says your integration looks healthy.

Exit code 1 when any error finding exists, so CI can fail the build, and 0 for pass, warn and inconclusive. Add --strict to exit 1 on anything but pass. An unusable config file exits 2.

Three lines of evidence

From 0.4.2 the report prints three evidence lines: Static (what the source scan found), Runtime trace (what a recorded run sent) and Live delivery (the --live ping). The top-level status is the static verdict, so a missing live check never turns a clean scan into a failure.

A wrapper that adds properties to every payload centrally declares enriches in ravensight.config.json, so the contract keys it supplies are not reported missing. An undeclared wrapper is reported as contract_prop_unproven at info, not as an error. Forwarding closures are resolved automatically, and forwarders declares the ones the scan cannot follow.

When the build injects the key (an .xcconfig value or a CI secret), declare ingestKey: { "source": "build" } and point the doctor at the built product with --bundle, so it checks the key that ships rather than one in source.

{
  "enriches": ["Analytics.logEvent"],
  "forwarders": ["Telemetry.send"],
  "ingestKey": { "source": "build" }
}

Check the built bundle

npx ravensight-doctor --bundle path/to/YourGame.app

The live check

--live proves the ingest key can deliver an event end to end. It reads the kill switch, opens a session with "platform": "doctor", sends one ravensight_doctor_ping whose data carries a random rs_doctor value, then reads it back from GET /api/v1/doctor/ping/:nonce every 2 seconds, at most 10 times. The server keeps doctor sessions out of your analytics and your event usage and allows them only that one event. A ping that is read back is reported as stored, with the time the server accepted it. One accepted but not read back within 20 seconds is the warning live_ping_unconfirmed. A bad key, tracking switched off, or a refused session or event is the error live_check_failed, with a note saying which step failed.

In CI

GitHub Actions

- uses: Reality-Software-Entertainment/ravensight-doctor@v0
  with:
    path: .
    report: true
    api-key: ${'$'}{{ secrets.RAVENSIGHT_INGEST_KEY }}

A GitLab CI snippet ships in the ravensight-doctor repo.

The report API

The doctor submits to POST /api/v1/doctor with your X-API-Key ingest key: an engine, a summary (pass, warn or fail with counts), and up to 100 findings. An inconclusive result is sent as warn, and the inventory and live result stay on your machine. One report is kept per game, newest wins, and it appears on the Implementation health card alongside the live signals.