Skip to main content

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.

MetricDescriptionGroup ByFiltersTime granularity
sessions_totalNumber of sessionsapp_version, os_version, os_major_version, country, top_n_market_nameapp_version, os_version, os_major_version, country, modelfive_minute, hourly, daily
crashes_totalNumber of crashesapp_version, os_version, os_major_version, country, top_n_market_nameapp_version, os_version, os_major_version, country, model, tag_name, tag_value, msgfive_minute, hourly, daily
network_requests_totalNumber of network requestsapp_version, os_version, os_major_version, country, top_n_market_nameapp_version, os_version, os_major_version, country, model, domain, path, method, status_codefive_minute, hourly, daily
anrs_totalNumber of ANR Samplesapp_version, os_version, os_major_version, country, top_n_market_nameapp_version, os_version, os_major_version, country, model, method, sample_typefive_minute, hourly, daily
moments_totalNumber of Momentsapp_version, os_version, os_major_version, country, top_n_market_nameapp_version, os_version, os_major_version, country, model, namefive_minute, hourly, daily
logs_totalNumber of Logsapp_version, os_version, os_major_version, country, top_n_market_nameapp_version, os_version, os_major_version, country, model, msg, typefive_minute, hourly, daily
spans_totalNumber of Spansapp_version, os_version, os_major_version, country, top_n_market_nameapp_version, os_version, os_major_version, country, model, name, outcome, span_attributefive_minute, hourly, daily

Supported Parameters for Filters

FilterMetricsTypeOperatorsExample
app_versionallstringeq, neq, in{"key": "app_version", "field_op": "eq", "val": "3.2.0"}
os_versionallstringeq, neq, in{"key": "os_version", "field_op": "eq", "val": "12.0"}
os_major_versionallinteq, neq, gt, gte, lt, lte, in{"key": "os_major_version", "field_op": "gt", "val": 9}
countryallstringeq, neq, in{"key": "country", "field_op": "eq", "val": "US"}
modelallstringeq, neq, like, nlike, in{"key": "model", "field_op": "eq", "val": "model1"}
has_anrsessions_totalbooleaneq{"key": "has_anr", "field_op": "eq", "val": true}
tag_namecrashes_totalstringeq, neq{"key": "tag_name", "field_op": "eq", "val": "crash_tag_name"}
tag_valuecrashes_totalstringeq, neq{"key": "tag_value", "field_op": "eq", "val": "crash_tag_value"}
msgcrashes_total, logs_totalstringlike{"key": "msg", "field_op": "like", "val": "substring"}
domainnetwork_requests_totalstringeq, neq, like, nlike, in{"key": "domain", "field_op": "like", "val": "example.com"}
pathnetwork_requests_totalstringeq, like{"key": "path", "field_op": "like", "val": "foo/bar"}
methodnetwork_requests_totalstringeq{"key": "method", "field_op": "eq", "val": "post"}
status_codenetwork_requests_totalrangeeq{"key": "status_code", "field_op": "eq", "val": {"start": 400", "end": 499}}
methodanrs_totalstringeq, like, in{"key": "method", "field_op": "like", "val": "com.foo.method"}
sample_typeanrs_totalstringeq, neq, in{"key": "sample_type", "field_op": "eq", "val": "first"}
namemoments_total, spans_totalstringeq, neq, like, nlike, in{"key": "name", "field_op": "eq", "val": "my_name"}
typelogs_totalstringeq{"key": "type", "field_op": "eq", "val": "error"}
outcomespans_totalstringeq{"key": "type", "field_op": "eq", "val": "successful"}
span_attributespans_totalpropertyeq, 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"
}