Uptrace JSON API

Uptrace Cloud provides the following API free of charge as long as you use it occasionally to read a small fraction of the ingested data, for example, a few requests per hour to read data for the last 1 hour is fine.

If you need more than that, please contact support to discuss your use case.

• Authentication
• Spans API
  • List spans
  • Query groups
• Alerting API
  • Create metrics monitor
  • Delete metrics monitor
• Annotations API

Authentication

To use the API below, you will need a project id (<project_id>) and an authentication token (<token>).

You can create an authentication token on your user profile page. The token will have the same permissions as the user, .i.e. you should be able to access the same projects.

Spans API

List spans

You can retrieve a list of spans like this:

curl https://api.uptrace.dev/api/v1/tracing/<project_id>/spans?time_gte=2023-07-10T00:00:00Z&time_lt=2023-07-11T00:00:00Z \
  --header "Authorization: Bearer <token>"

Supported query params:

Param		Comment
?time_gte=2023-07-10T00:00:00Z	Required	Time greater than or equal to time_gte.
?time_lt=2023-07-11T00:00:00Z	Required	Time lower than time_lt.
?trace_id=17706d68ea23cf9bc8976ca57d22ee31	Optional	Filter spans by trace id.
?id=12345	Optional	Filter spans by span id.
?parent_id=12345	Optional	Filter spans by parent span id.
?limit=10000	Optional	Limit number of spans.

Query groups

You can aggregate spans using UQL like this:

curl https://api.uptrace.dev/api/v1/tracing/<project_id>/groups?time_gte=2023-07-10T00:00:00Z&time_lt=2023-07-11T00:00:00Z&query=group%20by%20host_name \
  --header "Authorization: Bearer <token>"

Supported query params:

Param		Comment
?time_gte=2023-07-10T00:00:00Z	Required	Time greater than or equal to time_gte.
?time_lt=2023-07-11T00:00:00Z	Required	Time lower than time_lt.
?query=group by host_name	Optional	Aggregate spans with the query.
?limit=10000	Optional	Limit number of spans.
?search=option1|option2	Optional	Search for spans that contain option1 or option2.
?duration_gte=10000	Optional	Duration greater than or equal to N. Microseconds.
?duration_lt=100000	Optional	Duration greater than or equal to N. Microseconds.

Alerting API

Create metrics monitor

Request

To create a metrics monitor:

curl https://api2.uptrace.dev/internal/v1/projects/<project_id>/monitors \
  --request POST \
  --header "Authorization: Bearer <token>" \
  --header "Content-Type: application/json" \
  --data @monitor.json

Put the following contents in the monitor.json:

{
  "name": "Number of spans per minute",
  "type": "metric",
  "notifyEveryoneByEmail": true,
  "channelIds": [123],
  "params": {
    "metrics": [{ "name": "uptrace_tracing_spans", "alias": "spans" }],
    "query": "per_min(count($spans)) as spans | where service_name = 'myservice'",
    "column": "spans",
    "minAllowedValue": 100,
    "maxAllowedValue": 1000,
    "nullsMode": "convert"
  }
}

Supported JSON fields:

JSON field		Comment
name	Required. String.	Monitor name.
type	Required. String.	Must be set to metric.
notifyEveryoneByEmail	Optional. Bool.	Whether to notify everyone by email.
teamIds	Optional. Arrays of ints.	List of team ids to be notified by email. Overrides notifyEveryoneByEmail.
channelIds	Optional. Array of ints.	List of channel ids to send notifications.
params	Required. Object.	Metric monitor params. See below.

Manual metric monitors support the following params:

Param		Example
metrics	Required. Array.	[{"name": "uptrace_tracing_spans", "alias": "spans"}]
query	Required. String.	per_min(sum($spans)) as spans
column	Required. String.	Column name to monitor, e.g.spans.
minAllowedValue	Required*. Float.	Inclusive. Values lower than this are reported.
maxAllowedValue	Required. Float.	Inclusive. Values greater than this are reported.
groupingInterval	Optional. Float.	Grouping interval in milliseconds. The default 60000 (1 minute).
checkNumPoint	Optional. Int.	Number of points to check. The default is 5.
nullsMode	Optional. Enum.	Nulls handling mode: allow, forbid, convert. The default is allow.
timeOffset	Optional. Float.	Time offset in milliseconds, e.g. 60000 delays check by 1 minute.

* At least minAllowedValue or maxAllowedValue is required.

Response

The response looks like this:

{
  "monitor": {
    "id": "3807"
  }
}

You can use the monitor id to update/delete the monitor later.

Delete metrics monitor

To delete a metrics monitor:

curl https://api2.uptrace.dev/internal/v1/projects/<project_id>/monitors/<monitor_id> \
  --request DELETE \
  --header "Authorization: Bearer <token>"

Annotations API

See Annotations.