feat(develop-docs): Add timestamp to Metrics API

[philprime]

DESCRIBE YOUR PR

Problem

The current Metrics API (Sentry.metrics.count, .gauge, .distribution) always timestamps each metric at the moment the SDK method is called.
There is no way for the caller to supply a timestamp.

This is fine when application code emits metrics inline (e.g. incrementing a counter inside a request handler), but it breaks down for an important class of use cases: scraper-style collection, where an external process reads a batch of metrics from a source and then forwards them to Sentry.

Concrete example: Prometheus scraping

A Prometheus-compatible application exposes a /metrics endpoint that returns all current metric values in a single response:

# HELP go_memstats_heap_alloc_bytes Number of heap bytes allocated and still in use.
# TYPE go_memstats_heap_alloc_bytes gauge
go_memstats_heap_alloc_bytes 7.261032e+06

# HELP go_goroutines Number of goroutines that currently exist.
# TYPE go_goroutines gauge
go_goroutines 43

# HELP process_cpu_seconds_total Total user and system CPU time spent in seconds.
# TYPE process_cpu_seconds_total counter
process_cpu_seconds_total 11.32

# HELP promhttp_metric_handler_requests_in_flight Current number of scrapes being served.
# TYPE promhttp_metric_handler_requests_in_flight gauge
promhttp_metric_handler_requests_in_flight 1

A scraper fetches this snapshot at time T, then iterates through the metrics and calls Sentry.metrics.gauge(...), Sentry.metrics.count(...), etc. for each one.

Without a user-supplied timestamp, each SDK call captures Date.now() independently.
Even on a fast machine, iterating through dozens of metrics introduces sub-millisecond to low-millisecond drift between calls.
This means metrics that were observed at the exact same instant end up with slightly different timestamps.

This change is necessary if we want to extend our sentry-kubernetes integration to support Prometheus-style scraping of metrics in a Kubernetes cluster.

Why this matters: bucket boundaries

Sentry aggregates metrics into time buckets.
When two metrics that logically belong to the same observation are recorded with timestamps close to the bucket boundary, they land in different buckets.
This causes:

Metrics from the same scrape can be close to a bucket boundary, splitting a single observation into two partial data points and causing artificial jitter or gaps on dashboards and correlations.

The probability of hitting a bucket boundary increases with the number of metrics per scrape and the scrape frequency.

Solution

Add an optional timestamp parameter to the options object of all three metrics methods (count, gauge, distribution).

const scrapedAt = new Date();
const metrics = scrapePrometheusEndpoint(url);

for (const m of metrics) {
  Sentry.metrics.gauge(m.name, m.value, {
    timestamp: scrapedAt,  // all metrics share the same observation time
    attributes: m.labels,
  });
}

When provided, the SDK uses the caller's timestamp for the metric payload instead of Date.now().
When omitted, behavior is unchanged (current time).

Type

SDKs should accept the language's native date/time type for SDK user ergonomics:

Language	Native type
JavaScript	Date
Python	datetime
Java	Instant
Swift	Date
PHP	DateTimeInterface

The SDK converts to seconds-since-epoch for the wire format, which already has a required timestamp field.
This change should be aligned with the current implementation of the SDKs.

Alternative Approaches

Batching

The wire format already supports batching (the items array), but the public API is per-metric (count, gauge,distribution).
A batch API would be a much larger surface area change than necessary to resolve the issue.

Use beforeSendMetric to override the timestamp

This callback receives the metric object before sending, so it could theoretically mutate the timestamp.
But it runs at flush time (potentially seconds later), not at capture time, and it doesn't have access to the caller's intended timestamp without out-of-band state.

IS YOUR CHANGE URGENT?

Help us prioritize incoming PRs by letting us know when the change needs to go live.

• Urgent deadline (GA date, etc.):
• Other deadline:
• None: Not urgent, can wait up to 1 week+

SLA

• Teamwork makes the dream work, so please add a reviewer to your PRs.
• Please give the docs team up to 1 week to review your PR unless you've added an urgent due date to it.
  Thanks in advance for your help!

PRE-MERGE CHECKLIST

Make sure you've checked the following before merging your changes:

• Checked Vercel preview for correctness, including links
• PR was reviewed and approved by any necessary SMEs (subject matter experts)
• PR was reviewed and approved by a member of the Sentry docs team

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
develop-docs	Ready	Preview, Comment	May 18, 2026 2:09pm

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
sentry-docs	Ignored		May 18, 2026 2:09pm