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 few hours is fine.

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

API stability

The API is stable and will not change without a very good reason, such as reworking existing features or removing problematic functionality. Whenever possible, changes are made in a backward-compatible manner.

If you would like to be notified when the API changes, please send an email to support@uprace.dev explaining your use case.

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:

ParamComment
?time_gte=2023-07-10T00:00:00ZRequiredTime greater than or equal to time_gte.
?time_lt=2023-07-11T00:00:00ZRequiredTime lower than time_lt.
?trace_id=17706d68ea23cf9bc8976ca57d22ee31OptionalFilter spans by trace id.
?id=12345OptionalFilter spans by span id.
?parent_id=12345OptionalFilter spans by parent span id.
?limit=10000OptionalLimit 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:

ParamComment
?time_gte=2023-07-10T00:00:00ZRequiredTime greater than or equal to time_gte.
?time_lt=2023-07-11T00:00:00ZRequiredTime lower than time_lt.
?query=group by host_nameOptionalAggregate spans with the query.
?limit=10000OptionalLimit number of spans.
?search=option1|option2OptionalSearch for spans that contain option1 or option2.
?duration_gte=10000OptionalDuration greater than or equal to N. Microseconds.
?duration_lt=100000OptionalDuration greater than or equal to N. Microseconds.

Alerting API

Metric monitors

Create

Request

To create a metric 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,
  "teamIds": [123],
  "channelIds": [123],
  "params": {
    "metrics": [{ "name": "uptrace_tracing_spans", "alias": "spans" }],
    "query": "perMin(count($spans)) as spans | where service_name = 'myservice'",
    "column": "spans",
    "minAllowedValue": 100,
    "maxAllowedValue": 1000,
    "nullsMode": "convert"
  }
}

Supported JSON fields:

JSON fieldComment
nameRequired. String.Monitor name.
typeRequired. String.Must be set to metric.
notifyEveryoneByEmailOptional. Bool.Whether to notify everyone by email.
teamIdsOptional. Arrays of ints.List of team ids to be notified by email. Overrides notifyEveryoneByEmail.
channelIdsOptional. Array of ints.List of channel ids to send notifications.
paramsRequired. Object.Metric monitor params. See below.

Manual metric monitors support the following params:

ParamExample
metricsRequired. Array.[{"name": "uptrace_tracing_spans", "alias": "spans"}]
queryRequired. String.perMin(sum($spans)) as spans
columnRequired. String.Column name to monitor, e.g.spans.
minAllowedValueRequired*. Float.Inclusive. Values lower than this are reported.
maxAllowedValueRequired. Float.Inclusive. Values greater than this are reported.
groupingIntervalOptional. Float.Grouping interval in milliseconds. The default 60000 (1 minute).
checkNumPointOptional. Int.Number of points to check. The default is 5.
nullsModeOptional. Enum.Nulls handling mode: allow, forbid, convert. The default is allow.
timeOffsetOptional. 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.

Update

To update the metric monitor by id:

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

The monitor.json file should contain the same JSON fields that you used to create the monitor.

Response

The response looks like this:

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

Delete

To delete the metric monitor by id:

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

Error monitors

Create

Request

To create an error 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": "error",
  "notifyEveryoneByEmail": true,
  "teamIds": [123],
  "channelIds": [123],
  "params": {
    "metrics": [{ "name": "uptrace_tracing_logs", "alias": "logs" }],
    "query": "group by _group_id | where _system in ('log:error', 'log:fatal')"
  }
}

Supported JSON fields:

JSON fieldComment
nameRequired. String.Monitor name.
typeRequired. String.Must be set to error.
notifyEveryoneByEmailOptional. Bool.Whether to notify everyone by email.
teamIdsOptional. Arrays of ints.List of team ids to be notified by email. Overrides notifyEveryoneByEmail.
channelIdsOptional. Array of ints.List of channel ids to send notifications.
paramsRequired. Object.Metric monitor params. See below.

Error monitors support the following params:

ParamExample
metricsRequired. Array.[{"name": "uptrace_tracing_logs", "alias": "logs"}]
queryRequired. String.where _system in ('log:error', 'log:fatal')
Response

The response looks like this:

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

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

Update

To update the metric monitor by id:

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

The monitor.json file should contain the same JSON fields that you used to create the monitor.

Response

The response looks like this:

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

Delete

To delete the metric monitor by id:

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

Annotations API

See Annotations.

Last Updated: 11/18/2024, 8:59:51 AM