Reference
SDK Reference
Record outbound request failures and duration, then compare them with vendor incidents. The SDK is optional; repository scans and vendor alerts work without it.
@checkupstream/sdk 0.1.0 is on npm and records requests made with fetch. Version 0.2.0, which also records node:http, HTTP/2 and raw socket connections, is not published yet. The browser package and the other language SDKs are not on a public registry; contact us for access (opens in new tab).
Quickstart
Use a project SDK key from Settings → Credentials. Select the runtime where your requests run.
Review the data sent by the SDK before adding it. Request paths can contain personal data; request-ID samples and configured vendor account IDs have separate collection settings.
Package installation
npm install @checkupstream/sdkInitialization
Version 0.1.0 of @checkupstream/sdk patches globalThis.fetch so existing calls are instrumented with no per-request changes.
import { checkupstream } from "@checkupstream/sdk";
checkupstream.init({
sdkKey: "cup_sdk_your_key",
});
// Your existing fetch calls are now instrumented
const response = await fetch("https://api.stripe.com/v1/charges");
// Records this request's hostname, path, response status and duration.Graceful shutdown
process.on("SIGTERM", async () => {
await checkupstream.shutdown();
process.exit(0);
});This example instruments globalThis.fetch. Version 0.1.0 does not record requests made through node:http or node:https, which axios, got, the AWS SDK and Stripe’s Node client use; that is part of 0.2.0, which is not published yet. Check the integration recipe before using a different HTTP client or runtime.
Other languages (private beta)
Other language SDKs are in private beta and are not published to a package registry. Contact us with your runtime and HTTP client to confirm access and supported instrumentation.
Available beta runtimes7
- PythonDjango · FastAPI · Flaskrequests · httpx · urllib3Request access
- Gonet/http · Gin · Echo · Fiber · Chihttp.Transport wrapperRequest access
- RustAny HTTP clientrecord_http_call() per request; nothing is patchedRequest access
- RubyRails · Sinatra · HanamiNet::HTTPRequest access
- PHPLaravel · Symfony · SlimGuzzle middlewareRequest access
- JavaSpring Boot · Quarkus · Micronautinstrumented HttpClient wrapperRequest access
- .NETASP.NET Core · MVC · Minimal APIDelegatingHandler via IHttpClientFactoryRequest access
Configuration
The fields below apply to the Node.js and browser SDKs. Check the relevant package instructions for other languages.
CheckUpstreamConfig
sdkKeystringRequiredProject key beginning with cup_sdk_. Publishable in browser bundles. Secret API tokens (cup_api_) are rejected.
endpointstringOptionalTelemetry ingestion endpoint.
- Default:
"https://ingest.checkupstream.com/v1/events" servicesstring[]OptionalExact request hostnames, e.g. ["api.stripe.com"]. A slug such as "stripe" matches nothing. Omit to track all eligible hosts; browser first-party exclusions still apply.
- Default:
undefined flushIntervalMsnumberOptionalDefault flush interval in milliseconds. Explicit configuration and server directives can change it.
- Default:
30000 maxBatchSizenumberOptionalMaximum events per batch before auto-flush.
- Default:
100 enabledbooleanOptionalSet to false to disable the SDK entirely (useful for test environments).
- Default:
true
Telemetry events
Events contain the request hostname, path, method, status, duration and time. The SDK batches them for delivery.
Event and batch fields
TelemetryEvent
servicestringRequiredRequest hostname, e.g. "api.stripe.com". The field is named
serviceon the wire; the server maps the hostname to a service.endpointstringRequiredRequest path, e.g. "/v1/charges".
methodstringRequiredHTTP method, e.g. "GET".
statusnumberRequiredHTTP status code.
latency_msnumberRequiredRequest duration in milliseconds.
tsnumberRequiredUnix timestamp (seconds).
TelemetryBatch
sdk_keystringRequiredThe SDK Key (cup_sdk_*) used to authenticate the batch.
batchTelemetryEvent[]RequiredEvents with the TelemetryEvent fields above.
Auto-detected services
The server maps request hostnames to vendors. The SDK’s services option filters exact hostnames before delivery; use api.stripe.com, not stripe.
Example hostname mappings15
| Domain | Service |
|---|---|
api.stripe.com | Stripe |
api.openai.com | OpenAI |
api.anthropic.com | Anthropic |
s3.amazonaws.com | AWS S3 |
dynamodb.amazonaws.com | AWS DynamoDB |
api.twilio.com | Twilio |
api.sendgrid.com | SendGrid |
api.resend.com | Resend |
api.clerk.com | Clerk |
api.supabase.co | Supabase |
api.posthog.com | PostHog |
api.segment.io | Segment |
api.mixpanel.com | Mixpanel |
api.algolia.com | Algolia |
api.cloudinary.com | Cloudinary |
Troubleshooting
Find the matching message below for recovery steps. These codes identify the guides; some SDK messages do not print a code.
- SDK-001: Invalid SDK key
- SDK-002: Network timeout
- SDK-003: Rate limited
- SDK-004: Already initialized
- SDK-005: Invalid endpoint URL
- SDK-006: Flush failed
These errors concern SDK setup or telemetry delivery. They do not establish that a vendor or your application is down.
Common patterns
Restrict to specific services
Use exact request hostnames. Other hosts pass through without recording. A vendor slug such as stripe matches no requests.
checkupstream.init({
sdkKey: "cup_sdk_your_key",
services: ["api.stripe.com", "api.openai.com"],
});Disable in tests
Tie the SDK to your environment so unit tests don't ping the ingest endpoint.
checkupstream.init({
sdkKey: "cup_sdk_test_key",
enabled: process.env.NODE_ENV === "production",
});Read your SDK key from the environment. Keep secret API tokens out of source code and browser bundles. See credential permissions.
Plan your telemetry setup
Confirm runtime availability, then create a key for the project you want to measure.