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.

Check availability before installing

Node.js and browser packages are not on public npm yet. Contact us for access (opens in new tab) before using the examples below.

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 after release

Bash

npm install @checkupstream/sdk

Initialization

The @checkupstream/sdk package patches globalThis.fetch so existing calls are instrumented with no per-request changes.

TypeScript

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

TypeScript

process.on("SIGTERM", async () => {
  await checkupstream.shutdown();
  process.exit(0);
});

This example instruments globalThis.fetch. Check the integration recipe before using a different HTTP client or runtime.

Other languages (private beta)

Other language SDKs are in private beta. Contact us with your runtime and HTTP client to confirm access and supported instrumentation.

Available beta runtimes7

Python
Django · FastAPI · Flaskrequests · httpx · urllib3
Request access
Go
net/http · Gin · Echo · Fiber · Chihttp.Transport wrapper
Request access
Rust
Axum · Actix-web · Rocketreqwest::Client wrapper
Request access
Ruby
Rails · Sinatra · HanamiNet::HTTP
Request access
PHP
Laravel · Symfony · SlimGuzzle middleware
Request access
Java
Spring Boot · Quarkus · Micronautinstrumented HttpClient wrapper
Request access
.NET
ASP.NET Core · MVC · Minimal APIDelegatingHandler via IHttpClientFactory
Request access

Configuration

The fields below apply to the Node.js and browser SDKs. Check the relevant package instructions for other languages.

CheckUpstreamConfig

sdkKeystringRequired: Project key beginning with cup_sdk_. Publishable in browser bundles. Secret API tokens (cup_api_) are rejected.
endpointstringOptional: Telemetry ingestion endpoint.; Default: "https://ingest.checkupstream.com/v1/events"
servicesstring[]Optional: Exact 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
flushIntervalMsnumberOptional: Default flush interval in milliseconds. Explicit configuration and server directives can change it.; Default: Node.js: 30000; browser: 10000
maxBatchSizenumberOptional: Maximum events per batch before auto-flush.; Default: 100
enabledbooleanOptional: Set 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

servicestringRequired: Request hostname, e.g. "api.stripe.com". The field is named service on the wire; the server maps the hostname to a service.
endpointstringRequired: Request path, e.g. "/v1/charges".
methodstringRequired: HTTP method, e.g. "GET".
statusnumberRequired: HTTP status code.
latency_msnumberRequired: Request duration in milliseconds.
tsnumberRequired: Unix timestamp (seconds).

TelemetryBatch

sdk_keystringRequired: The SDK Key (cup_sdk_*) used to authenticate the batch.
batchTelemetryEvent[]Required: Events 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.

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.

TypeScript

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.

TypeScript

checkupstream.init({
  sdkKey: "cup_sdk_test_key",
  enabled: process.env.NODE_ENV === "production",
});

Tip

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.

Manage SDK keys Integration Recipes