Check Your Setup
Run risicare doctor when no traces arrive. It checks the key, the endpoint, the network and a test span, one line for each check.
risicare doctor checks, one line for each check, that spans from this host can reach Risicare. Use it when no trace appears in the dashboard. It is a command of the Python SDK. The JavaScript SDK does not have it yet.
Run it
pip install risicare adds the console script risicare. Run the command with the same environment as your application: RISICARE_API_KEY, RISICARE_ENDPOINT, RISICARE_SERVICE_NAME and the proxy variables.
risicare doctorThe output looks like this:
$ risicare doctor
risicare doctor <version> (Python 3.12.13, httpx 0.28.1)
[PASS] SDK version: risicare <version> is installed; <version> is the newest on PyPI.
[PASS] API key: set: prefix "rsk-", 36 characters.
[INFO] Endpoint: https://ingest.risicare.ai (spans go here; environment production).
[INFO] Proxy: no proxy variable is set. No proxy applies to https URLs: the connection to the endpoint is direct.
[PASS] Reachable: https://ingest.risicare.ai answered HTTP 200 in 84 ms.
[PASS] Clock: this host and the endpoint differ by 0 s (limit 300 s).
[PASS] Key accepted: POST /v1/spans with no span: HTTP 200. The gateway takes the key.
[PASS] Test span: the gateway accepted 1 span: risicare.doctor, trace 4f1c… (service checkout-api, environment production). It shows in Traces of the project of this key within a short time.
[INFO] Instrumentations: installed in this Python environment, and patched when your application calls init(): openai 3.57.0.
Result: the gateway accepted the test span. Exit code 0.
Read the output
The first line names the version of the command, Python and httpx. Then each check gives one line, in this format:
[PASS|WARN|FAIL|INFO] {Check}: {text}
PASS: the check passed.INFO: the line gives a fact. It is not a problem.WARNandFAIL: the line ends withNext:and the next step.
When the gateway refuses the key, the line has the same text as the WARNING of the SDK. See What the outage WARNING says for each answer.
The last line is the result. It is one of these three lines:
| Result line | Exit code |
|---|---|
Result: the gateway accepted the test span. Exit code 0. | 0 |
Result: the gateway takes the key; no span was sent, so delivery is not proven. Exit code 3. | 3 |
Result: no span was accepted. Fix the first FAIL line (Reachable) first. Exit code 1. | 1 |
The sentence Fix the first FAIL line (...) first. is in the last line when a check gave a FAIL. It names that check. Here it names Reachable as an example. An error in the command line, for example --timeout nan, exits with code 2.
Only exit code 0 proves delivery. Exit code 3 is for --no-send: the key is good, and no span was sent. A script cannot read it as proof that spans arrive.
The checks
The checks run in this order.
| Check | What it does |
|---|---|
SDK version | Shows the installed version and the newest version on PyPI. It gives an INFO line when it cannot read PyPI. |
API key | Shows that a key is set, with its prefix and its length. The command reads the key as init() reads it. White space at an end of the key is removed, and a WARN line says so. White space inside the key, or a character that is not ASCII, is a FAIL. |
Endpoint | Shows the endpoint that gets the spans, and the environment. |
Proxy | Names the proxy variables that are set, and the rule that httpx (the HTTP client of the SDK) applies to the endpoint: a proxy, NO_PROXY, or a direct connection. |
Reachable | Sends GET <endpoint>/health with no key. Any HTTP answer shows that the host is reachable. |
Clock | Compares the Date header of that answer with the clock of this host. |
Key accepted | Sends POST <endpoint>/v1/spans with no span, so it stores nothing. Any 2xx answer shows that the gateway takes the key. |
Test span | Sends POST <endpoint>/v1/spans with one span, through the exporter of the SDK. |
Instrumentations | Names the libraries that are installed in this Python environment and that the SDK patches when your application calls init(). The command runs in its own process, so it reports the environment and not the process of your application. |
The test span
The test span goes to the real project of the key. Look for it in Traces. It is as small as possible:
- It is one span of kind INTERNAL, named
risicare.doctor, with the attributerisicare.doctorset totrue. - It has
service.namefromRISICARE_SERVICE_NAME, and the environment ofinit()(RISICARE_ENVIRONMENT, elsedevelopment). You find it in the project and the environment of your own spans. - It has no LLM data, no tokens, no LLM cost and no content.
- It counts as one event toward the quota of the organization.
With --no-send, the command sends no span.
Options
| Option | What it does |
|---|---|
--no-send | Sends no test span, so nothing is written to the project. The command stops after the key check and exits with code 3. |
--endpoint URL | Checks this ingest gateway URL. The default is RISICARE_ENDPOINT, then the default gateway. |
--timeout SECONDS | Sets the time for each request. The default is 10. |
--no-version-check | Does not read the newest version from PyPI. |
Safe to paste
You can paste the output in a support thread.
- It shows the key only as a prefix and a length.
- It never shows the user name or the password of a URL or of a proxy value. A proxy value that the command cannot read with certainty shows only
<NAME> is set. - It shows no content.
- The log lines of the SDK during the two requests are not in the report. A rejection reason goes into the
Test spanline, with the key removed.
What the command sends
The Key accepted check and the Test span check send the API key to the endpoint. The command sends nothing else, and it makes requests only to your endpoint, with one more read of https://pypi.org/pypi/risicare/json for the newest version. --no-version-check turns that read off.
When import risicare already ran init()
With RISICARE_TRACING=true, import risicare runs init() in the process of the command too. An INFO line then says import risicare already ran init() in this process (for example with RISICARE_TRACING=true)…. The command does not use that client, and that client can make requests of its own (for example fix reads with RISICARE_FIX_RUNTIME=true).
JavaScript
The JavaScript SDK has no doctor command. If no trace arrives, read the WARNING that the SDK writes to stderr. A line that starts with [risicare] WARNING: Risicare: spans are NOT reaching names the cause. See What the outage WARNING says for each answer.