Embrace Custom Metrics API
The Embrace Custom Metrics API allows you to manage (create, get and delete) the custom metrics of your organization. These will be available via the Metrics API and can also be forwarded to your organization's observability platform of choice.
You can follow this guide to see how queries custom metrics.
Prerequisites
- Embrace Custom Metrics API Token. Contact an Embrace onboarding specialist to get this token for your organization. Once you receive the token, you can proceed independently with creating custom metrics.
Supported Metrics
The following metrics are supported to create using the API.
Metric | Description | Group By | Filters | Time granularity |
---|---|---|---|---|
sessions_total | Number of sessions | app_version, os_version, os_major_version, country, top_n_market_name | app_version, os_version, os_major_version, country, model | five_minute, hourly, daily |
crashes_total | Number of crashes | app_version, os_version, os_major_version, country, top_n_market_name | app_version, os_version, os_major_version, country, model, tag_name, tag_value, msg | five_minute, hourly, daily |
network_requests_total | Number of network requests | app_version, os_version, os_major_version, country, top_n_market_name | app_version, os_version, os_major_version, country, model, domain, path, method, status_code | five_minute, hourly, daily |
anrs_total | Number of ANR Samples | app_version, os_version, os_major_version, country, top_n_market_name | app_version, os_version, os_major_version, country, model, method, sample_type | five_minute, hourly, daily |
moments_total | Number of Moments | app_version, os_version, os_major_version, country, top_n_market_name | app_version, os_version, os_major_version, country, model, name | five_minute, hourly, daily |
logs_total | Number of Logs | app_version, os_version, os_major_version, country, top_n_market_name | app_version, os_version, os_major_version, country, model, msg, type | five_minute, hourly, daily |
spans_total | Number of Spans | app_version, os_version, os_major_version, country, top_n_market_name | app_version, os_version, os_major_version, country, model, name, outcome, span_attribute | five_minute, hourly, daily |
Supported Parameters for Filters
Filter | Metrics | Type | Operators | Example |
---|---|---|---|---|
app_version | all | string | eq, neq, in | {"key": "app_version", "field_op": "eq", "val": "3.2.0"} |
os_version | all | string | eq, neq, in | {"key": "os_version", "field_op": "eq", "val": "12.0"} |
os_major_version | all | int | eq, neq, gt, gte, lt, lte, in | {"key": "os_major_version", "field_op": "gt", "val": 9} |
country | all | string | eq, neq, in | {"key": "country", "field_op": "eq", "val": "US"} |
model | all | string | eq, neq, like, nlike, in | {"key": "model", "field_op": "eq", "val": "model1"} |
has_anr | sessions_total | boolean | eq | {"key": "has_anr", "field_op": "eq", "val": true} |
tag_name | crashes_total | string | eq, neq | {"key": "tag_name", "field_op": "eq", "val": "crash_tag_name"} |
tag_value | crashes_total | string | eq, neq | {"key": "tag_value", "field_op": "eq", "val": "crash_tag_value"} |
msg | crashes_total, logs_total | string | like | {"key": "msg", "field_op": "like", "val": "substring"} |
domain | network_requests_total | string | eq, neq, like, nlike, in | {"key": "domain", "field_op": "like", "val": "example.com"} |
path | network_requests_total | string | eq, like | {"key": "path", "field_op": "like", "val": "foo/bar"} |
method | network_requests_total | string | eq | {"key": "method", "field_op": "eq", "val": "post"} |
status_code | network_requests_total | range | eq | {"key": "status_code", "field_op": "eq", "val": {"start": 400", "end": 499}} |
method | anrs_total | string | eq, like, in | {"key": "method", "field_op": "like", "val": "com.foo.method"} |
sample_type | anrs_total | string | eq, neq, in | {"key": "sample_type", "field_op": "eq", "val": "first"} |
name | moments_total, spans_total | string | eq, neq, like, nlike, in | {"key": "name", "field_op": "eq", "val": "my_name"} |
type | logs_total | string | eq | {"key": "type", "field_op": "eq", "val": "error"} |
outcome | spans_total | string | eq | {"key": "type", "field_op": "eq", "val": "successful"} |
span_attribute | spans_total | property | eq, neq | {"key": "type", "field_op": "eq", "val": {"property_key": "k1", "property_values": ["v1", "v2"]}} |
API Endpoints
All the endpoints have the same authentication and authorization method, url and parameters.
URL
:https://api.embrace.io/custom-metrics
Request
Headers:
Authorization
: we are going to use a Bearer token to authorize and authenticate our requests. i.e.:Authorization: Bearer 7bd49186fed24af699cf93069fc64f03
.
URL Params:
app_id
: application id in which we are going to manage the custom metrics. i.e.:appID1
custom_metric_name
: custom metric name that we use to identify it. i.e.:my_custom_metric_name
Body Params:
name
: name you want to provide this new metric i.e.:my_custom_metric_name
metric
: base Embrace metric this new metric will be built from. i.e.:sessions_total
.group_by
: list of group by that we are going to use to group the metric. It can be empty. i.e.:["os_version", "app_version"]
.filters
list of filters that we are going to apply on the metric. It can be empty. i.e.:
{
"op": "and",
"children": [
{
"field_op": "eq",
"key": "os_version",
"val": "12"
}
]
}
time_granularity
: list of granularity that we are going to support on this metric. If it is empty, by default hourly is turned on. i.e.:["five_minute", "hourly", "daily"]
Response
Body Params:
custom_metric_id
: the unique ID for the metric created. i.e.:XZ5BDQk
Status codes:
200
: request was successful and we return a body with new information.204
: request was successful and we don't return a body.400
: the url params and body were not correct.403
: you don't have access to execute that operation.404
: metric that you are trying to consume doesn't exist.409
: metric that you are trying to create already exists.500
: there was an internal error and you should retry later.
Create custom metric
Request
curl --location 'https://api.embrace.io/custom-metrics/api/v1/app/appID1/custom-metrics' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer 1b6be81cd01c4b08833295efadccafdc' \
--data '{
"name": "sessions_total_v1",
"metric": "sessions_total",
"group_by": ["app_version"],
"filters": {
"op":"and",
"children":[{"field_op":"eq","key":"os_version","val":"12"}]
},
"time_granularity": ["five_minute", "hourly"]
}'
Response
Status codes: 200
, 400
, 403
, 409
and 500
.
OK
{
"custom_metric_id": "y8vayvn",
"app_id": "appID1",
"name": "sessions_total_v1",
"metric": "sessions_total",
"filters": {
"op": "and",
"children": [
{
"field_op": "eq",
"key": "os_version",
"val": "12"
}
]
},
"group_by": [
"app_version"
],
"time_granularity": [
"five_minute",
"hourly"
]
}
Error (500)
{
"message": "we had an internal error, please try again later"
}
Get custom metrics
Request
curl --location 'https://api.embrace.io/custom-metrics/api/v1/app/appID1/custom-metrics' \
--header 'Authorization: Bearer 1b6be81cd01c4b08833295efadccafdc'
Response
Status codes: 200
, 400
, 409
and 500
.
OK (200)
{
"results": [
{
"custom_metric_id": "XZ5BDQk",
"app_id": "appID1",
"name": "sessions_total_v1",
"metric": "sessions_total",
"filters": {},
"group_by": [
"app_version"
],
"time_granularity": [
"five_minute",
"hourly"
]
}
]
}
Error (400)
{
"message": "app id can't be empty"
}
Delete custom metrics
Request
curl -X DELETE --location 'https://api.embrace.io/custom-metrics/api/v1/app/appID1/custom-metrics/sessions_total_v1' \
--header 'Authorization: Bearer 1b6be81cd01c4b08833295efadccafdc'
Response
Status codes: 204
, 400
, 403
, 404
, 409
and 500
.
OK (204), body is empty
Error (404)
{
"message": "metric sessions_total_v1 doesn't exist"
}