This documents describes the current state of the REST services provided by the Plumbr Server.

General

Data format in JSON responses

Dates

dates in JSON responses are always returned as absolute timestamps represented by integer (time passed since epoch in milliseconds).

Strings

strings are formatted in UTF 8.

Authentication

Every REST service provided by Plumbr Server requires an authentication. Only HTTP Basic authentication mechanism is currently supported for external clients. Using httpie tool the username can be provided as follows:

http --auth your@mail.com https://app.plumbr.io/api/v3/users/summary

You will be asked for the password via standard input.

Account

Although all data returned by Plumbr Server REST services is always constrained by the account that user belongs to, the account identifier is never passed in the request as input. Account of the currently logged in user is retrieved by a service server-side whenever such service requires it.

Date range

Any request should be accompanied by a date range. All data, returned by a request, unless specified otherwise, is relevant to the date range provided.

Date range can be specified in two formats – relative and absolute.

Relative time

Relative time is specified as a single parameter interpreted as an amount of hours or days in the past before the current time.

last

1h|2h|4h|12h|24h|7d|30d

last time units (h=hours, d=days) to display.

Absolute time

Absolute time is specified by two explicit time boundaries - upper and lower. Time ranges are passed in a textual form which are interpreted in an account’s time zone.

startDate

timestamp in text form: 2015-06-26T00:00

start of the date range

endDate

timestamp in text form: 2015-06-26T00:00

end of the date range

Sorting

Any request which returns a list, must accept sorting parameters.

_sort

[+|-][field]

specify a field name to sort by. + means ascending order (default), - means descending order. Note, that url should be encoded, so that '+' encoded as '%2B'

Pagination

All lists support pagination via two parameters, pageSize and pageNumber.

Contexts

All summary and list queries (see examples further below in this document) can be put in a context. E.g. simple query

give me a list of all services accessed during last 24h

can be put in a context of an application:

give me a list of all services of the given application accessed during last 24h

or in a context of an user:

give me a list of all services accessed during last 24h by the given user

or in a context of a root cause:

give me a list of all services affected by the given root cause during last 24h

To specify a context of some query just add context parameter to it. The general form is context=<contextName>=<contextValue>. E.g. for queries above (please note that the = between the name and the value should be url-encoded):

$ http GET 'https://app.plumbr.io/api/v3/services?last=24h'
$ http GET 'https://app.plumbr.io/api/v3/services?context=applicationName%3DDashboard&last=24h'
$ http GET 'https://app.plumbr.io/api/v3/services?context=userId%3Dnikem@plumbr.eu&last=24h'
$ http GET 'https://app.plumbr.io/api/v3/services?context=rootCause%3D68&last=24h'

In case of a root cause the context value is the id of the root cause.

Filters

All list queries can have an extra filtering for each textual field in the result in the form filter=<fieldName>=<someText> E.g. having the simple query (please note that the = between the name and the value should be url-encoded):

give me a list of all users accessing my applications during last 24h
$ http GET 'https://app.plumbr.io/api/v3/users?last=24h'

we can add a filter to only return some users:

give me a list of all users from plumbr.eu domain accessing my applications during last 24h
$ http GET 'https://app.plumbr.io/api/v3/services?last=24h&filter=userId%3Dplumbr.eu'

Filters match if field’s value has a substring equal to the provided criteria. If list has multiple textual fields, you can combine filters using || (again, url-encoded):

give me a list of all users from plumbr.eu domain accessing my production applications during last 24h
$ http GET 'https://app.plumbr.io/api/v3/services?last=24h&filter=userId%3Dplumbr.eu%7C%7CapplicationName%3Dproduction'

Impact (V4 API only, in beta)

The numerically expressed impact in most (but not all) lists, summaries and charts can be expressed in either number of transactions or number of users affected. It means that e.g. I might be interested, how many failed transactions this particular service had, or, how many different users wasn’t able to use this particular service because of failures.

By default, the impact is expressed in number of users impacted (where relevant of course, there is no point to show impact in user numbers in users list, it would be always 1 for instance). However, impact can be easily expressed in number of transactions by using the showTransactions=true parameter.

Show me the list of services in user impact:
$ http GET 'https://app.plumbr.io/api/v4/services?last=24h'
Show me the list of services in transaction impact:
$ http GET 'https://app.plumbr.io/api/v4/services?last=24h&showTransactions=true'

Users

Summary

/api/v4/users/summary

Gets the summary of users' activity for a given time range. When compare is set to false, there is single row always returned. When compare is set to true, then first row is comparison baseline (30d average) and second row are numbers corresponding to current time interval.

Sample request
$ http GET 'https://app.plumbr.io/api/v4/users/summary?last=24h' 'Accept:application/json'
Sample response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 205

[ {
  "satisfiedUsers" : 11,
  "verySlowUsers" : 3,
  "onlySlowUsers" : 0,
  "failedUsers" : 3,
  "totalUsers" : 17,
  "success" : 11,
  "verySlow" : 3,
  "onlySlow" : 0,
  "failed" : 3,
  "total" : 17
} ]
Response fields description
Path Type Description

[].totalUsers

Number

Total number of different users in given context

[].satisfiedUsers

Number

Number of different users that did not have any problems in given context

[].failedUsers

Number

Number of different users who experienced failures in given context

[].verySlowUsers

Number

Number of different users who experienced very slow transactions in given context

[].onlySlowUsers

Number

Number of different users who experienced slow, but not very slow transactions in given context

[].total

Number

Total number of different users in given context

[].success

Number

Number of different users that did not have any problems in given context

[].failed

Number

Number of different users who experienced failures in given context

[].verySlow

Number

Number of different users who experienced very slow transactions in given context

[].onlySlow

Number

Number of different users who experienced slow, but not very slow transactions in given context

With compare enabled:

Sample request
$ http GET 'https://app.plumbr.io/api/v4/users/summary?last=24h&compare=true' 'Accept:application/json'
Sample response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 408

[ {
  "satisfiedUsers" : 10,
  "verySlowUsers" : 2,
  "onlySlowUsers" : 1,
  "failedUsers" : 2,
  "totalUsers" : 16,
  "success" : 10,
  "verySlow" : 2,
  "onlySlow" : 1,
  "failed" : 2,
  "total" : 16
}, {
  "satisfiedUsers" : 11,
  "verySlowUsers" : 3,
  "onlySlowUsers" : 0,
  "failedUsers" : 3,
  "totalUsers" : 17,
  "success" : 11,
  "verySlow" : 3,
  "onlySlow" : 0,
  "failed" : 3,
  "total" : 17
} ]

List of users

/api/v4/users

Gets the list of all active users. Metrics in users list are always expressed in transaction impact numbers.

Sample request
$ http GET 'https://app.plumbr.io/api/v4/users?last=24h' 'Accept:application/json'
Sample response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 460

{
  "hasMore" : true,
  "totalCount" : 19245,
  "sort" : {
    "sortOnBackend" : true,
    "field" : null,
    "sortDirection" : null
  },
  "items" : [ {
    "userId" : "5632",
    "userIdentity" : "Mart",
    "success" : 5,
    "verySlow" : 2,
    "onlySlow" : 1,
    "failed" : 2,
    "total" : 10
  }, {
    "userId" : "562",
    "userIdentity" : "Pets",
    "success" : 5,
    "verySlow" : 2,
    "onlySlow" : 1,
    "failed" : 2,
    "total" : 10
  } ]
}
Response fields description
Path Type Description

items[].userId

String

User identity, if detected. User id otherwise.

items[].userIdentity

String

User identity, if detected. Null otherwise

items[].total

Number

Total number of transactions made by this user in this context

items[].success

Number

Total number of successful transactions made by this user in this context

items[].failed

Number

Total number of failed transactions made by this user in this context

items[].onlySlow

Number

Total number of slow transactions made by this user in this context that were not considered very slow

items[].verySlow

Number

Total number of very slow transactions made by this user in this context

totalCount

Number

Total count of all users active during given period and in this context

hasMore

Boolean

Are there more rows on next pages

sort

Object

Sort conditions

Additional examples (see also Contexts and Filters):

A list of all users accessing the Dashboard application during last 24h

$ http GET 'https://app.plumbr.io/api/v4/users?last=24h&context=applicationName%3DDashboard'

A list of all users from plumbr.eu domain accessing the Dashboard application during last 24h

$ http GET 'https://app.plumbr.io/api/v4/users?last=24h&context=applicationName%3DDashboard&filter=userId%3Dplumbr.eu'

A list of all users from plumbr.eu domain accessing the Dashboard application during last 24h ordered by descending total number of transactions

$ http GET 'https://app.plumbr.io/api/v4/users?last=24h&context=applicationName%3DDashboard&filter=userId%3Dplumbr.eu&sort=-total'

Single user overview

The following requests form an overview of a single user activities during some time period.

User transactions overview (see [transactions_summary]):

$ http GET 'https://app.plumbr.io/api/v3/transactions/summary?context=userId%3Duser@plumbr.eu&last=24h'

Number of distinct service count for a single user (v4, in beta):

$ http GET 'https://app.plumbr.io/api/v4/services/count?context=userId%3Duser@plumbr.eu&last=24h'

Number of unhealthy transactions for a single user:

$ http GET 'https://app.plumbr.io/api/v3/transactions/count?context=userId%3Duser@plumbr.eu&last=24h&metrics=slow,failed'

where metric can have any combination of the three values success, slow, failed, separated by coma. The result will be the sum of the number of transactions with the corresponding status

Number of root causes impacting a single user:

$ http GET 'https://app.plumbr.io/api/v3/root-causes/count?context=userId%3Duser@plumbr.eu&last=24h'

Applications

List of applications

/api/v4/applications

Gets the list of all applications monitored during given time period (API v4, in beta).

Sample request in user impact
$ http GET 'https://app.plumbr.io/api/v4/applications?last=24h' 'Accept:application/json'
Sample response in user impact
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 704

{
  "hasMore" : false,
  "totalCount" : 2,
  "sort" : {
    "sortOnBackend" : true,
    "field" : null,
    "sortDirection" : null
  },
  "items" : [ {
    "applicationName" : "https://app.plumbr.io",
    "failedTrend" : 123,
    "verySlowTrend" : 345,
    "historicalTotal" : 2332,
    "active" : true,
    "hasJvm" : false,
    "success" : 10,
    "verySlow" : 1,
    "failed" : 2,
    "onlySlow" : 0,
    "total" : 13
  }, {
    "applicationName" : "https://portal.plumbr.eu",
    "failedTrend" : 2,
    "verySlowTrend" : 56,
    "historicalTotal" : 124,
    "active" : false,
    "hasJvm" : false,
    "success" : 11,
    "verySlow" : 3,
    "failed" : 3,
    "onlySlow" : 0,
    "total" : 17
  } ]
}
Response fields description
Path Type Description

items[].applicationName

String

Application name

items[].total

Number

Total number of different users that used this application

items[].success

Number

Number of different users that did not have any problems with this application

items[].failed

Number

Number of different users who experienced failures with this application

items[].failedTrend

Number

Mean of the failed users who experienced failures for the last 30 days

items[].verySlow

Number

Number of different users who experienced very slow transactions with this application

items[].verySlowTrend

Number

Mean of the users who experienced very slow apps for the last 30 days

items[].onlySlow

Number

Always 0 for application users query

items[].active

Boolean

Is this application currently active

items[].hasJvm

Boolean

Is this application currently have any connected JVM

items[].historicalTotal

Number

Total number of users for the past 30 days

totalCount

Number

Total count of all applications active during given period

hasMore

Boolean

Are there more rows on next pages

sort

Object

Sort conditions

Sample request in tx impact
$ http GET 'https://app.plumbr.io/api/v4/applications?last=24h&showTransactions=true' 'Accept:application/json'
Sample response in tx impact
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 702

{
  "hasMore" : false,
  "totalCount" : 2,
  "sort" : {
    "sortOnBackend" : true,
    "field" : null,
    "sortDirection" : null
  },
  "items" : [ {
    "applicationName" : "https://app.plumbr.io",
    "failedTrend" : 123,
    "verySlowTrend" : 345,
    "historicalTotal" : 2332,
    "active" : true,
    "hasJvm" : false,
    "success" : 5,
    "verySlow" : 2,
    "failed" : 2,
    "onlySlow" : 1,
    "total" : 10
  }, {
    "applicationName" : "https://portal.plumbr.eu",
    "failedTrend" : 2,
    "verySlowTrend" : 56,
    "historicalTotal" : 124,
    "active" : false,
    "hasJvm" : false,
    "success" : 5,
    "verySlow" : 2,
    "failed" : 2,
    "onlySlow" : 1,
    "total" : 10
  } ]
}
Response fields description
Path Type Description

items[].applicationName

String

Application name

items[].total

Number

Total number of transactions on this application

items[].success

Number

Total number of successful transactions on this application

items[].failed

Number

Total number of failed transactions on this application

items[].failedTrend

Number

Mean of the failed transactions for the last 30 days

items[].onlySlow

Number

Total number of slow transactions on this application that were not considered very slow

items[].verySlow

Number

Total number of very slow transactions on this application

items[].verySlowTrend

Number

Mean of the very slow transactions for the last 30 days

items[].active

Boolean

Is this application currently active

items[].hasJvm

Boolean

Is this application currently have any connected JVM

items[].historicalTotal

Number

Total number of transactions for the past 30 days

totalCount

Number

Total count of all applications active during given period

hasMore

Boolean

Are there more rows on next pages

sort

Object

Sort conditions

Additional examples (see also Contexts and Filters):

A list of all applications used by user boss@example.com during last 24h

$ http GET 'https://app.plumbr.io/api/v4/applications?context=userId%3Dboss@example.com&last=24h'

A list of all applications used by user boss@example.com during last 24h in tx impact

$ http GET 'https://app.plumbr.io/api/v4/applications?context=userId%3Dboss@example.com&last=24h&showTransactions=true'
---
A list of all applications from `.com` domain monitored during last 24h

$ http GET 'https://app.plumbr.io/api/v4/applications?last=24h&filter=applicationName%3D.com'

A list of all application monitored during last 24h ordered by descending total number of transactions

$ http GET 'https://app.plumbr.io/api/v4/applications?last=24h&sort=-total&showTransactions=true'

Single application overview

The following requests form an overview of a single application during some time period.

User transactions overview (see [transactions_summary]):

$ http GET 'https://app.plumbr.io/api/v3/transactions/summary?context=applicationName%3Dapp.plumbr.io&last=24h

Number of (unhealthy) services for a single application:

$ http GET 'https://app.plumbr.io/api/v3/services/count?context=applicationName%3Dapp.plumbr.io&last=24h&metrics=total

where metric can have one of the three values total, healthy or unhealthy.

Number of (unhealthy) transactions for a single application:

$ http GET 'https://app.plumbr.io/api/v3/transactions/count?context=applicationName%3Dapp.plumbr.io&last=24h&metrics=slow,failed

where metric can have any combination of the three values success, slow, failed, separated by coma. The result will be the sum of the number of transactions with the corresponding status.

Number of (unhappy) users for a single application:

$ http GET 'https://app.plumbr.io/api/v3/users/count?context=applicationName%3Dapp.plumbr.io&last=24h&metrics=unhappy

where metric can have any combination of the three values unhappy, happy, total, separated by coma. The result will be the sum of the number of users with the corresponding status.

Number of root causes impacting a single application:

$ http GET 'https://app.plumbr.io/api/v3/root-causes/count?context=applicationName%3Dapp.plumbr.io&last=24h

Total downtime of a single application during given time period

$ http GET 'https://app.plumbr.io/api/v3/applications/downtimes/count?context=applicationName%3Dapp.plumbr.io&last=24h

The result will be in milliseconds.

Services

Summary

/api/v3/services/summary

Gets the summary of all monitored services for a given time range. Always returns an array of size 1.

Sample request

Unresolved directive in services.adoc - include::/var/lib/jenkins/workspace/Portal/portal/build/generated-snippets/services-summary/httpie-request.adoc[]

Sample response

Unresolved directive in services.adoc - include::/var/lib/jenkins/workspace/Portal/portal/build/generated-snippets/services-summary/http-response.adoc[]

Response fields description

Unresolved directive in services.adoc - include::/var/lib/jenkins/workspace/Portal/portal/build/generated-snippets/services-summary/response-fields.adoc[]

Compare this to the day before. Returns an array of size 2, where the last element represents current period, and the first element represents the previous period of the same length.

Sample request

Unresolved directive in services.adoc - include::/var/lib/jenkins/workspace/Portal/portal/build/generated-snippets/services-summary-compare/httpie-request.adoc[]

Sample response

Unresolved directive in services.adoc - include::/var/lib/jenkins/workspace/Portal/portal/build/generated-snippets/services-summary-compare/http-response.adoc[]

List of services

/api/v4/services

Gets the list of all monitored services (API v4, in beta).

Sample request in user impact
$ http GET 'https://app.plumbr.io/api/v4/services?last=24h' 'Accept:application/json'
Sample response in user impact
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 531

{
  "hasMore" : false,
  "totalCount" : 2,
  "sort" : {
    "sortOnBackend" : true,
    "field" : null,
    "sortDirection" : null
  },
  "items" : [ {
    "serviceId" : "5632",
    "serviceName" : "/api/{1}/userData",
    "wastedTime" : 100500,
    "success" : 10,
    "failed" : 2,
    "onlySlow" : 0,
    "verySlow" : 1,
    "total" : 13
  }, {
    "serviceId" : "124",
    "serviceName" : "ServicesController.quickSearch()",
    "success" : 11,
    "failed" : 3,
    "onlySlow" : 0,
    "verySlow" : 3,
    "total" : 17
  } ]
}
Response fields description
Path Type Description

items[].serviceId

String

Internal id of the service. Used in several other queries

items[].serviceName

String

Human readable name of the service

items[].wastedTime

Number

How much time was gone over service threshold (measured in milliseconds)

items[].total

Number

Total number of different users that used this service

items[].success

Number

Number of different users that did not have any problems with this service

items[].failed

Number

Number of different users who experienced failures with this service

items[].verySlow

Number

Number of different users who experienced very slow transactions with this service

items[].onlySlow

Number

Always 0 for services query

totalCount

Number

Total count of all services active during given period

hasMore

Boolean

Are there more rows on next pages

sort

Object

Sort conditions

Sample request in tx impact
$ http GET 'https://app.plumbr.io/api/v4/services?last=24h&showTransactions=true' 'Accept:application/json'
Sample response in tx impact
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 529

{
  "hasMore" : false,
  "totalCount" : 2,
  "sort" : {
    "sortOnBackend" : true,
    "field" : null,
    "sortDirection" : null
  },
  "items" : [ {
    "serviceId" : "5632",
    "serviceName" : "/api/{1}/userData",
    "wastedTime" : 100500,
    "success" : 5,
    "failed" : 2,
    "onlySlow" : 1,
    "verySlow" : 2,
    "total" : 10
  }, {
    "serviceId" : "124",
    "serviceName" : "ServicesController.quickSearch()",
    "success" : 5,
    "failed" : 2,
    "onlySlow" : 1,
    "verySlow" : 2,
    "total" : 10
  } ]
}
Response fields description
Path Type Description

items[].serviceId

String

Internal id of the service. Used in several other queries

items[].serviceName

String

Human readable name of the service

items[].wastedTime

Number

How much time was gone over service threshold (measured in milliseconds)

items[].total

Number

Total number of transactions made on this service

items[].success

Number

Total number of successful transactions on this service

items[].failed

Number

Total number of failed transactions on this service

items[].onlySlow

Number

Total number of slow transactions on this service that were not considered very slow

items[].verySlow

Number

Total number of very slow transactions on this service

totalCount

Number

Total count of all services active during given period

hasMore

Boolean

Are there more rows on next pages

sort

Object

Sort conditions

Additional examples (see also Contexts and Filters):

A list of all used services from the Dashboard application during last 24h

$ http GET 'https://app.plumbr.io/api/v4/services?last=24h&context=applicationName%3DDashboard'

A list of all services having Payment in their names from the Dashboard application during last 24h

$ http GET 'https://app.plumbr.io/api/v4/services?last=24h&context=applicationName%3DDashboard&filter=serviceName%3Dpayment'

A list of all services having Payment in their names from the Dashboard application during last 24h ordered by the number of failed transactions

$ http GET 'https://app.plumbr.io/api/v4/services?last=24h&context=applicationName%3DDashboard&filter=serviceName%3Dpayment&sort=-failed'

Single service overview

The following requests form an overview of a single service during some time period.

Service transactions overview (see [transactions_summary]):

$ http GET 'https://app.plumbr.io/api/v3/transactions/summary?context=serviceId%3D12345ABC&last=24h'

Number of unhappy users for a single service:

$ http GET 'https://app.plumbr.io/api/v3/users/count?context=serviceId%3D12345ABC&last=24h&metrics=unhappy'

where metric can have any combination of the three values unhappy, happy, total, separated by coma. The result will be the sum of the number of users with the corresponding status.

Number of unhealthy transactions for a single service:

$ http GET 'https://app.plumbr.io/api/v3/transactions/count?context=serviceId%3D12345ABC&last=24h&metrics=slow,failed'

where metric can have any combination of the three values success, slow, failed, separated by coma. The result will be the sum of the number of transactions with the corresponding status

Number of root causes impacting a single service:

$ http GET 'https://app.plumbr.io/api/v3/root-causes/count?context=serviceId%3D12345ABC&last=24h'

Latency percentiles of all invocations of a single service

Sample request

Unresolved directive in services.adoc - include::/var/lib/jenkins/workspace/Portal/portal/build/generated-snippets/transactions-percentiles/httpie-request.adoc[]

Sample response

Unresolved directive in services.adoc - include::/var/lib/jenkins/workspace/Portal/portal/build/generated-snippets/transactions-percentiles/http-response.adoc[]

Response fields description

Unresolved directive in services.adoc - include::/var/lib/jenkins/workspace/Portal/portal/build/generated-snippets/transactions-percentiles/response-fields.adoc[] Unresolved directive in index.adoc - include::rootCauses.adoc[] == Transactions

Summary

/api/v4/transactions/summary

Gets the summary of all monitored transactions for a given time range. When compare is set to false, there is single row always returned. When compare is set, then first row is comparison baseline (30d average) and second row are numbers corresponding to current time interval.

Sample request without compare
$ http GET 'https://app.plumbr.io/api/v4/transactions/summary?last=24h' 'Accept:application/json'
Sample response without compare
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 91

[ {
  "total" : 10,
  "success" : 5,
  "failed" : 2,
  "onlySlow" : 1,
  "verySlow" : 2
} ]
Response fields description
Path Type Description

[].total

Number

Total number of monitored transactions

[].success

Number

Number of successful transactions

[].verySlow

Number

Number of very slow transactions

[].onlySlow

Number

Number of slow transactions that were not considered very slow

[].failed

Number

Number of failed transactions

Sample request with compare
$ http GET 'https://app.plumbr.io/api/v4/transactions/summary?last=24h&compare=true' 'Accept:application/json'
Sample response with compare
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 180

[ {
  "total" : 10,
  "success" : 8,
  "failed" : 1,
  "onlySlow" : 1,
  "verySlow" : 1
}, {
  "total" : 10,
  "success" : 5,
  "failed" : 2,
  "onlySlow" : 1,
  "verySlow" : 2
} ]
Response fields description
Path Type Description

[0].total

Number

Average total number of monitored transactions in compare baseline

[0].success

Number

Average total number of successful transactions in compare baseline

[0].verySlow

Number

Average total number of very slow transactions in compare baseline

[0].onlySlow

Number

Average total number of slow transactions in compare baseline that were not considered very slow

[0].failed

Number

Average total number of failed transactions in compare baseline

[1].total

Number

Total number of monitored transactions in current period

[1].success

Number

Number of successful transactions in current period

[1].verySlow

Number

Number of very slow transactions in current period

[1].onlySlow

Number

Number of slow transactions in current period that were not considered very slow

[1].failed

Number

Number of failed transactions in current period

Percentiles Summary

/api/v4/transactions/percentiles/summary

Gets the percentiles summary of all monitored transactions for a given time range. When compare is set to false, there is single row always returned. When compare is set to true, then first row is comparison baseline (30d average) and second row are numbers corresponding to current time interval.

Sample request without compare
$ http GET 'https://app.plumbr.io/api/v4/transactions/percentile/summary?last=24h&context=serviceId%253D1245' 'Accept:application/json'
Sample response without compare
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 114

[ {
  "max" : 2613,
  "p50" : 37,
  "p90" : 212,
  "p95" : 253,
  "p99" : 363,
  "p999" : 521,
  "total" : 123
} ]
Response fields description
Path Type Description

[].max

Number

Maximum response time

[].p50

Number

50th percentile or median of response time

[].p90

Number

90th percentile

[].p95

Number

95th percentile

[].p99

Number

99th percentile

[].p999

Number

99.9th percentile

[].total

Number

Total duration of all transactions

Sample request with compare
$ http GET 'https://app.plumbr.io/api/v4/transactions/percentile/summary?last=24h&context=serviceId%253D1245&compare=true' 'Accept:application/json'
Sample response with compare
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 226

[ {
  "max" : 2610,
  "p50" : 39,
  "p90" : 210,
  "p95" : 256,
  "p99" : 360,
  "p999" : 527,
  "total" : 124
}, {
  "max" : 2613,
  "p50" : 37,
  "p90" : 212,
  "p95" : 253,
  "p99" : 363,
  "p999" : 521,
  "total" : 123
} ]
Response fields description
Path Type Description

[0].max

Number

Maximum response time in comparison period

[0].p50

Number

50th percentile or median of response time in comparison period

[0].p90

Number

90th percentile in comparison period

[0].p95

Number

95th percentile in comparison period

[0].p99

Number

99th percentile in comparison period

[0].p999

Number

99.9th percentile in comparison period

[0].total

Number

Total duration of all transactions in comparison period

[1].max

Number

Maximum response time

[1].p50

Number

50th percentile or median of response time

[1].p90

Number

90th percentile

[1].p95

Number

95th percentile

[1].p99

Number

99th percentile

[1].p999

Number

99.9th percentile

[1].total

Number

Total duration of all transactions

Runtime Application Architecture

Runtime Application Architecture (RAA) is a dynamic directed network graph composed of the data gathered from networked transactions, job invocations and in general all the network connections that originate from any monitored jvm.

Data in this graph is relevant only in selected period of time. Where appropriate, edges on the graph are annotated with corresponding transaction or job invocation metrics.

There are three types of nodes that can exist in RAA graph:

  • Upstream nodes (UPSTREAM) - applications, through which transactional traffic reaches JVMs

  • JVM nodes (JVM) - jvms monitored by Plumbr

  • Downstream nodes (DOWNSTREAM) - any networked endpoint, not monitored by Plumbr and identified by hostname/ip and port. It can be a database, some external http endpoint, etc

Between upstream node and JVM node, traffic is always measured in number of transactions.

Between jvm node and another jvm node, traffic is always measured in number of transactions.

Between jvm node and downstream node, traffic is never measured in number of transactions. Instead, connection between jvm and downstream node means that during selected time period, a networked connection existed between jvm node and downstream destination node. Also, this networked connection is not accounted in the context of upstream application.

There can be no direct interaction between upstream node and downstream node.

Currently, distributed tracing between JVMs via Plumbr agent supports only HTTP traffic.

Runtime architecture graph

/api/v3/raa

Gets the runtime architecture graph of all monitored jvms with generic metrics in particular query context.

JVM → downstream traffic is not tracked in the context of particular Application.

Legal query contexts are: [applicationName, jvmId, downstreamName, downstreamGroup], where:

  • jvmId - the id of jvm. Corresponds to 'key' value of the jvm node (edge.from.type = JVM or edge.to.type = JVM)

  • applicationName - the name of the application, corresponds to 'key' value of the upstream node (edge.from.type = UPSTREAM)

  • downstreamName - the 'key' of the downstream node (edge.to.type = DOWNSTREAM)

  • downstreamGroup - if downstream node was collapsed into protocol or port group, it’s the 'key' of the collapsed downstream node

Pay attention, that:

  • applicationName context is not applied to jvm → downstream edges (as JVM → downstream traffic is not tracked in the context of particular Application).

  • downstreamName and downstreamGroup contexts are not applicable to upstream → jvm and jvm → jvm edges. If specified, upstream → jvm and jvm → jvm relations are not queried.

By default, returned graph size is tuned for optimal visual rendering. If query results in graph with more than 40 unique jvm nodes, an error message is returned instead.

If graph has many upstream and downstream nodes, the least significant downstream nodes and upstream nodes are "squashed" or collapsed into single node or node groups. Preferably, nodes with heavier traffic or larger number of dependants are not collapsed, but there are several other criterion the default collapse algorithm bases on. To override default behaviour of node collapsing, one can specify the number of top surviving nodes via following parameters:

  • upstreamCollapseThreshold

  • downstreamCollapseThreshold

With large enough values for upstreamCollapseThreshold and downstreamCollapseThreshold, a full graph can be returned.

Sample request
$ http GET 'https://app.plumbr.io/api/v3/raa?last=24h' 'Accept:application/json'
Sample response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 2397

{
  "jvmNames" : {
    "prodJvm1" : "Prod node 1",
    "prodJvm2" : "Prod node 2"
  },
  "edges" : [ {
    "from" : {
      "key" : "new-york",
      "type" : "UPSTREAM"
    },
    "to" : {
      "key" : "prodJvm1",
      "type" : "JVM"
    },
    "protocol" : "http",
    "port" : 80,
    "metrics" : {
      "count" : 0,
      "txMetrics" : {
        "count" : 0,
        "slow" : 0,
        "failed" : 0,
        "verySlow" : 0,
        "onlySlow" : 0
      }
    }
  }, {
    "from" : {
      "key" : "london",
      "type" : "UPSTREAM"
    },
    "to" : {
      "key" : "prodJvm1",
      "type" : "JVM"
    },
    "protocol" : "http",
    "port" : 80,
    "metrics" : {
      "count" : 0,
      "txMetrics" : {
        "count" : 0,
        "slow" : 0,
        "failed" : 0,
        "verySlow" : 0,
        "onlySlow" : 0
      }
    }
  }, {
    "from" : {
      "key" : "paris",
      "type" : "UPSTREAM"
    },
    "to" : {
      "key" : "prodJvm2",
      "type" : "JVM"
    },
    "protocol" : "http",
    "port" : 80,
    "metrics" : {
      "count" : 0,
      "txMetrics" : {
        "count" : 0,
        "slow" : 0,
        "failed" : 0,
        "verySlow" : 0,
        "onlySlow" : 0
      }
    }
  }, {
    "from" : {
      "key" : "COLLAPSED",
      "type" : "UPSTREAM"
    },
    "to" : {
      "key" : "prodJvm2",
      "type" : "JVM"
    },
    "protocol" : "http",
    "port" : 80,
    "metrics" : {
      "count" : 0,
      "txMetrics" : {
        "count" : 0,
        "slow" : 0,
        "failed" : 0,
        "verySlow" : 0,
        "onlySlow" : 0
      }
    }
  }, {
    "from" : {
      "key" : "prodJvm2",
      "type" : "JVM"
    },
    "to" : {
      "key" : "third-party-http.com:443",
      "type" : "DOWNSTREAM"
    },
    "protocol" : "https",
    "port" : 443,
    "metrics" : {
      "count" : 0,
      "txMetrics" : {
        "count" : 0,
        "slow" : 0,
        "failed" : 0,
        "verySlow" : 0,
        "onlySlow" : 0
      }
    }
  }, {
    "from" : {
      "key" : "prodJvm1",
      "type" : "JVM"
    },
    "to" : {
      "key" : "third-party-http.com:443",
      "type" : "DOWNSTREAM"
    },
    "protocol" : "https",
    "port" : 443,
    "metrics" : {
      "count" : 0,
      "txMetrics" : {
        "count" : 0,
        "slow" : 0,
        "failed" : 0,
        "verySlow" : 0,
        "onlySlow" : 0
      }
    }
  } ],
  "messages" : [ ]
}
Response fields description
Path Type Description

edges

Array

Set of graph edges, composed of nodes on both sides, edge meta-info and metrics.

edges[].from

Object

Source node. Either upstream node (application) or JVM.

edges[].from.key

Varies

Source node identifier/name.

edges[].from.type

String

Source node type, one of UPSTREAM or JVM.

edges[].from.collapsed

Boolean

An optional marker, if set to true, indicates that several nodes were imploded into single node to fit into visual representation of graph.

edges[].from.collapsedCount

Number

An optional field. The number of nodes that were imploded.

edges[].to

Object

Target node. Either another JVM or downstream node (database, external HTTP resource, etc).

edges[].to.key

String

Target node identifier/name.

edges[].to.type

String

Target node type, one of of JVM or DOWNSTREAM.

edges[].to.collapsed

Boolean

An optional marker, if set to true, indicates that several nodes were imploded into single node to fit into visual representation of graph.

edges[].to.collapsedCount

Number

An optional field. The number of nodes that were imploded.

edges[].protocol

Varies

Protocol that was used for networked request, if known and relevant.

edges[].port

Varies

Port that was used for networked request, if known and relevant.

edges[].metrics

Object

Metrics gathered for this particular network edge in this particular direction.

edges[].metrics.count

Number

Total number of operations on this particular network edge in this particular direction.

edges[].metrics.txMetrics

Object

Transactions on this particular network edge in this particular direction.

edges[].metrics.txMetrics.count

Number

Total number of transactions.

edges[].metrics.txMetrics.slow

Number

Number of slow transactions.

edges[].metrics.txMetrics.failed

Number

Number of failed transactions.

jvmNames

Object

The map of jvmId > human readable jvmName. The API-friendly key of JVM node is a non-human-friendly jvmId, this map can be used to translate that into human friendly name.

messages

Array

List of explanatory info- or error message strings, if any.

Subgraph of all jvms that had at least one upstream integration point.

/api/v3/raa/upstreams

Gets the subgraph of upstream application → any jvm endpoints in particular query context. This query complements the /api/v3/raa query, in that it can return list of nodes collapsed in the first place.

Upstream nodes are collapsed in this list only when number of different upstream endpoints is very high.

Legal query contexts are: [applicationName, jvmId]

Resulting graph is

Sample request
$ http GET 'https://app.plumbr.io/api/v3/raa/upstreams?last=24h' 'Accept:application/json'
Sample response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 1584

{
  "jvmNames" : {
    "prodJvm1" : "Prod node 1"
  },
  "edges" : [ {
    "from" : {
      "key" : "new-york",
      "type" : "UPSTREAM"
    },
    "to" : {
      "key" : "prodJvm1",
      "type" : "JVM"
    },
    "protocol" : "http",
    "port" : 80,
    "metrics" : {
      "count" : 0,
      "txMetrics" : {
        "count" : 0,
        "slow" : 0,
        "failed" : 0,
        "verySlow" : 0,
        "onlySlow" : 0
      }
    }
  }, {
    "from" : {
      "key" : "london",
      "type" : "UPSTREAM"
    },
    "to" : {
      "key" : "prodJvm1",
      "type" : "JVM"
    },
    "protocol" : "http",
    "port" : 80,
    "metrics" : {
      "count" : 0,
      "txMetrics" : {
        "count" : 0,
        "slow" : 0,
        "failed" : 0,
        "verySlow" : 0,
        "onlySlow" : 0
      }
    }
  }, {
    "from" : {
      "key" : "paris",
      "type" : "UPSTREAM"
    },
    "to" : {
      "key" : "prodJvm1",
      "type" : "JVM"
    },
    "protocol" : "http",
    "port" : 80,
    "metrics" : {
      "count" : 0,
      "txMetrics" : {
        "count" : 0,
        "slow" : 0,
        "failed" : 0,
        "verySlow" : 0,
        "onlySlow" : 0
      }
    }
  }, {
    "from" : {
      "key" : "administrative",
      "type" : "UPSTREAM"
    },
    "to" : {
      "key" : "prodJvm1",
      "type" : "JVM"
    },
    "protocol" : "http",
    "port" : 80,
    "metrics" : {
      "count" : 0,
      "txMetrics" : {
        "count" : 0,
        "slow" : 0,
        "failed" : 0,
        "verySlow" : 0,
        "onlySlow" : 0
      }
    }
  } ],
  "messages" : [ ]
}
Response fields description
Path Type Description

edges

Array

Subgraph which contains only upstream → any jvm targeted edges, order be transaction count desc. If number of upstreams is too big, only upstreams with largest number of transactions are kept and rest are collapsed.

jvmNames

Object

The map of jvmId > human readable jvmName. The API-friendly key of JVM node is a non-human-friendly jvmId, this map can be used to translate that into human friendly name.

messages

Array

List of explanatory info- or error message strings, if any.

Subgraph of all jvms that had at least one downstream integration endpoint.

/api/v3/raa/downstreams

Gets the subgraph of jvm → downstream integration endpoints in particular query context. This query complements the /api/v3/raa query, in that it can return list of nodes collapsed in the first place.

Downstream nodes are never collapsed in this list.

Legal query contexts are: [jvmId, downstreamName, downstreamGroup]

Sample request
$ http GET 'https://app.plumbr.io/api/v3/raa/downstreams?last=24h' 'Accept:application/json'
Sample response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 1681

{
  "jvmNames" : {
    "prodJvm1" : "Prod node 1",
    "prodJvm2" : "Prod node 2"
  },
  "edges" : [ {
    "from" : {
      "key" : "prodJvm1",
      "type" : "JVM"
    },
    "to" : {
      "key" : "fourth-party-http.com:443",
      "type" : "DOWNSTREAM"
    },
    "protocol" : "https",
    "port" : 443,
    "metrics" : {
      "count" : 0,
      "txMetrics" : {
        "count" : 0,
        "slow" : 0,
        "failed" : 0,
        "verySlow" : 0,
        "onlySlow" : 0
      }
    }
  }, {
    "from" : {
      "key" : "prodJvm2",
      "type" : "JVM"
    },
    "to" : {
      "key" : "localhost:3306",
      "type" : "DOWNSTREAM"
    },
    "protocol" : "MySQL",
    "port" : 3306,
    "metrics" : {
      "count" : 0,
      "txMetrics" : {
        "count" : 0,
        "slow" : 0,
        "failed" : 0,
        "verySlow" : 0,
        "onlySlow" : 0
      }
    }
  }, {
    "from" : {
      "key" : "prodJvm2",
      "type" : "JVM"
    },
    "to" : {
      "key" : "localhost:5432",
      "type" : "DOWNSTREAM"
    },
    "protocol" : "Postgres",
    "port" : 3306,
    "metrics" : {
      "count" : 0,
      "txMetrics" : {
        "count" : 0,
        "slow" : 0,
        "failed" : 0,
        "verySlow" : 0,
        "onlySlow" : 0
      }
    }
  }, {
    "from" : {
      "key" : "prodJvm1",
      "type" : "JVM"
    },
    "to" : {
      "key" : "third-party-http.com:443",
      "type" : "DOWNSTREAM"
    },
    "protocol" : "https",
    "port" : 443,
    "metrics" : {
      "count" : 0,
      "txMetrics" : {
        "count" : 0,
        "slow" : 0,
        "failed" : 0,
        "verySlow" : 0,
        "onlySlow" : 0
      }
    }
  } ],
  "messages" : [ ]
}
Response fields description
Path Type Description

edges

Array

Subgraph which contains only jvm → downstream edges. Downstream nodes are never collapsed on this downstreams-listing query.

jvmNames

Object

The map of jvmId > human readable jvmName. The API-friendly key of JVM node is a non-human-friendly jvmId, this map can be used to translate that into human friendly name.

messages

Array

List of explanatory info- or error message strings, if any.