Overview

Media Type

The API uses JSON to communicate with clients.

You should add the following accept header to your requests:

Accept: application/json

When you send JSON data with a POST or PUT request, you must add the following content type header:

Content-Type: application/json

Tenant Header

Hawkular APM is a multi-tenant system. Your requests to tenant-dependent resources must include a tenant header:

Hawkular-Tenant: my-tenant

Timestamps

The API understands all timestamps as milliseconds since January 1, 1970, 00:00:00 UTC.

Response codes

Resources in the API follow response codes conventions, listed below.

Table 1. Response codes conventions
Response code Meaning

200 Ok

The operation completed successfully.

201 Created

A POST or PUT operation to create an entity completed successfully. The reponse should contain a Location header.

204 No Content

The operation completed successfully but result entity is null (object) or empty (array). Empty arrays are not sent in the response body.

400 Bad Request

The operation could not be processed. It could be due to:

  • Missing or malformed request entity

  • Missing header/query parameter

  • Malformed path/header/query parameter

  • Invalid parameters (breaking business rules)

404 Not Found

Resource denoted by the URI does not exist.

405 Method Not Allowed

Resource denoted by the URI does not support the operation type.

406 Not Acceptable

Cannot reply in a format accepted by the client (specified in Accept request header).

409 Conflict

A POST or PUT operation could not be performed because it conflicts with an existing entity.

415 Unsupported Media Type

Invalid request entity format. For example, text/plain whereas application/json is expected.

500 Internal Server Error

Resource operation failed unexpectedly.

503 Service Unavailable

The server failed to initialize or the storage backend is not ready yet.

Error responses

Error responses may include an [ApiError] entity in the body.

Sample error entity
{"errorMsg":"Tenant is not specified. Use 'Hawkular-Tenant' header."}

Base Path

/hawkular/apm/

REST APIs

analytics

  1. Identify the bound endpoints for a transaction

  2. Get the trace communication summary statistics associated with criteria

  3. Get the host names associated with the criteria

  4. Get the trace node timeseries statistics associated with criteria

  5. Get the trace node summary statistics associated with criteria

  6. Get property information

  7. Get the trace completion count

  8. Get the number of trace instances that returned a fault

  9. Get the trace completion fault details associated with criteria

  10. Get the trace completion percentiles associated with criteria

  11. Get the trace completion property details associated with criteria

  12. Get the trace completion timeseries statistics associated with criteria

  13. Get the trace completion times associated with criteria

  14. Get transaction information

  15. Identify the unbound endpoints

Endpoint GET /analytics/boundendpoints/{name}

Note
 Identify the bound endpoints for a transaction

Path parameters

Parameter Required Description Type Format Allowable Values

name

Yes

transaction name

string

-

-

Query parameters

Parameter Required Description Type Format Allowable Values

startTime

No

optional 'start' time, default 1 hour before current time

integer

int64

-

endTime

No

optional 'end' time, default current time

integer

int64

-

Response

Status codes

Status Code Reason Response Model

200

Success

array of object

500

Internal server error

-

Endpoint GET /analytics/communication/summary

Note
 Get the trace communication summary statistics associated with criteria

Query parameters

Parameter Required Description Type Format Allowable Values

tree

No

tree

boolean

-

-

criteria

No

-

string

-

-

Response

Status codes

Status Code Reason Response Model

200

Success

array of object

500

Internal server error

-

Endpoint GET /analytics/hostnames

Note
 Get the host names associated with the criteria

Query parameters

Parameter Required Description Type Format Allowable Values

criteria

No

-

string

-

-

Response

Status codes

Status Code Reason Response Model

200

Success

array of object

500

Internal server error

-

Endpoint GET /analytics/node/statistics

Note
 Get the trace node timeseries statistics associated with criteria

Query parameters

Parameter Required Description Type Format Allowable Values

interval

No

-

integer

int64

-

criteria

No

-

string

-

-

Response

Status codes

Status Code Reason Response Model

200

Success

array of object

500

Internal server error

-

Endpoint GET /analytics/node/summary

Note
 Get the trace node summary statistics associated with criteria

Query parameters

Parameter Required Description Type Format Allowable Values

criteria

No

-

string

-

-

Response

Status codes

Status Code Reason Response Model

200

Success

array of object

500

Internal server error

-

Endpoint GET /analytics/properties

Note
 Get property information

Query parameters

Parameter Required Description Type Format Allowable Values

criteria

No

-

string

-

-

Response

Status codes

Status Code Reason Response Model

200

Success

array of object

500

Internal server error

-

Endpoint GET /analytics/trace/completion/count

Note
 Get the trace completion count

Query parameters

Parameter Required Description Type Format Allowable Values

criteria

No

-

string

-

-

Response

Status codes

Status Code Reason Response Model

200

Success

integer

500

Internal server error

-

Endpoint GET /analytics/trace/completion/faultcount

Note
 Get the number of trace instances that returned a fault

Query parameters

Parameter Required Description Type Format Allowable Values

criteria

No

-

string

-

-

Response

Status codes

Status Code Reason Response Model

200

Success

integer

500

Internal server error

-

Endpoint GET /analytics/trace/completion/faults

Note
 Get the trace completion fault details associated with criteria

Query parameters

Parameter Required Description Type Format Allowable Values

criteria

No

-

string

-

-

Response

Status codes

Status Code Reason Response Model

200

Success

array of object

500

Internal server error

-

Endpoint GET /analytics/trace/completion/percentiles

Note
 Get the trace completion percentiles associated with criteria

Query parameters

Parameter Required Description Type Format Allowable Values

criteria

No

-

string

-

-

Response

Status codes

Status Code Reason Response Model

200

Success

Percentiles

500

Internal server error

-

Endpoint GET /analytics/trace/completion/property/{property}

Note
 Get the trace completion property details associated with criteria

Path parameters

Parameter Required Description Type Format Allowable Values

property

No

property

string

-

-

Query parameters

Parameter Required Description Type Format Allowable Values

criteria

No

-

string

-

-

Response

Status codes

Status Code Reason Response Model

200

Success

array of object

500

Internal server error

-

Endpoint GET /analytics/trace/completion/statistics

Note
 Get the trace completion timeseries statistics associated with criteria

Query parameters

Parameter Required Description Type Format Allowable Values

interval

No

-

integer

int64

-

criteria

No

-

string

-

-

Response

Status codes

Status Code Reason Response Model

200

Success

array of object

500

Internal server error

-

Endpoint GET /analytics/trace/completion/times

Note
 Get the trace completion times associated with criteria

Query parameters

Parameter Required Description Type Format Allowable Values

criteria

No

-

string

-

-

Response

Status codes

Status Code Reason Response Model

200

Success

array of object

500

Internal server error

-

Endpoint GET /analytics/transactions

Note
 Get transaction information

Query parameters

Parameter Required Description Type Format Allowable Values

criteria

No

-

string

-

-

Response

Status codes

Status Code Reason Response Model

200

Success

array of object

500

Internal server error

-

Endpoint GET /analytics/unboundendpoints

Note
 Identify the unbound endpoints

Query parameters

Parameter Required Description Type Format Allowable Values

startTime

No

optional 'start' time, default 1 hour before current time

integer

int64

-

endTime

No

optional 'end' time, default current time

integer

int64

-

compress

No

compress list to show common patterns

boolean

-

-

Response

Status codes

Status Code Reason Response Model

200

Success

array of object

500

Internal server error

-

config

  1. Retrieve the collector configuration for the optionally specified host and server

  2. Retrieve the transaction configurations, changed since an optional specified time

  3. Add or update the transaction configurations

  4. Remove the transaction configuration with the specified name

  5. Retrieve the transaction configuration for the specified name

  6. Add or update the transaction configuration for the specified name

  7. Retrieve the transaction summaries

  8. Validate the transaction configuration

Endpoint GET /config/collector

Note
 Retrieve the collector configuration for the optionally specified host and server

Query parameters

Parameter Required Description Type Format Allowable Values

type

No

optional type

string

-

-

host

No

optional host name

string

-

-

server

No

optional server name

string

-

-

Response

Status codes

Status Code Reason Response Model

200

Success

CollectorConfiguration

500

Internal server error

-

Endpoint GET /config/transaction/full

Note
 Retrieve the transaction configurations, changed since an optional specified time

Query parameters

Parameter Required Description Type Format Allowable Values

updated

No

updated since

integer

int64

-

Response

Status codes

Status Code Reason Response Model

200

Success

object

500

Internal server error

-

Endpoint POST /config/transaction/full

Note
 Add or update the transaction configurations

Response

Status codes

Status Code Reason Response Model

200

Success

array of object

500

Internal server error

-

Endpoint DELETE /config/transaction/full/{name}

Note
 Remove the transaction configuration with the specified name

Path parameters

Parameter Required Description Type Format Allowable Values

name

Yes

transaction name

string

-

-

Response

Status codes

Status Code Reason Response Model

200

Success

-

500

Internal server error

-

Endpoint GET /config/transaction/full/{name}

Note
 Retrieve the transaction configuration for the specified name

Path parameters

Parameter Required Description Type Format Allowable Values

name

Yes

transaction name

string

-

-

Response

Status codes

Status Code Reason Response Model

200

Success

TransactionConfig

500

Internal server error

-

Endpoint PUT /config/transaction/full/{name}

Note
 Add or update the transaction configuration for the specified name

Path parameters

Parameter Required Description Type Format Allowable Values

name

Yes

transaction name

string

-

-

Response

Status codes

Status Code Reason Response Model

200

Success

array of object

500

Internal server error

-

Endpoint GET /config/transaction/summary

Note
 Retrieve the transaction summaries

Response

Status codes

Status Code Reason Response Model

200

Success

array of object

500

Internal server error

-

Endpoint POST /config/transaction/validate

Note
 Validate the transaction configuration

Response

Status codes

Status Code Reason Response Model

200

Success

array of object

500

Internal server error

-

traces

  1. Retrieve end to end trace for specified id

  2. Add a list of trace fragments

  3. Query trace fragments associated with criteria

  4. Retrieve trace fragment for specified id

Endpoint GET /traces/complete/{id}

Note
 Retrieve end to end trace for specified id

Path parameters

Parameter Required Description Type Format Allowable Values

id

Yes

id of required record

string

-

-

Response

Status codes

Status Code Reason Response Model

200

Success, trace found and returned

Trace

404

Unknown trace id

-

500

Internal server error

-

Endpoint POST /traces/fragments

Note
 Add a list of trace fragments

Body

Required Description Data Type

Yes

List of traces

array of Trace

Response

Status codes

Status Code Reason Response Model

200

Adding traces succeeded.

-

500

Unexpected error happened while storing the trace fragments

-

Endpoint GET /traces/fragments/search

Note
 Query trace fragments associated with criteria

Query parameters

Parameter Required Description Type Format Allowable Values

criteria

No

-

string

-

-

Response

Status codes

Status Code Reason Response Model

200

Success

Trace

500

Internal server error

-

Endpoint GET /traces/fragments/{id}

Note
 Retrieve trace fragment for specified id

Path parameters

Parameter Required Description Type Format Allowable Values

id

Yes

id of required record

string

-

-

Response

Status codes

Status Code Reason Response Model

200

Success, trace found and returned

Trace

404

Unknown fragment id

-

500

Internal server error

-

Data Types

AddContentAction

Inherits: ProcessorAction

Name Required Description Type Format Allowable Values

expression

No

-

Expression

-

-

name

No

-

string

-

-

type

No

-

string

-

-

AddCorrelationIdAction

Inherits: ProcessorAction

Name Required Description Type Format Allowable Values

expression

No

-

Expression

-

-

scope

No

-

string

-

Interaction, ControlFlow, CausedBy

AssertComplete

Inherits: InstrumentAction

CollectorConfiguration

Name Required Description Type Format Allowable Values

instrumentation

No

-

object

-

-

properties

No

-

object

-

-

transactions

No

-

object

-

-

CompleteCorrelation

Inherits: InstrumentAction

Name Required Description Type Format Allowable Values

allowSpawn

No

-

boolean

-

-

idExpression

No

-

string

-

-

Component

Inherits: InteractionNode

Name Required Description Type Format Allowable Values

componentType

No

-

string

-

-

Consumer

Inherits: InteractionNode

Name Required Description Type Format Allowable Values

endpointType

No

-

string

-

-

ContainerNode

Inherits: Node

Name Required Description Type Format Allowable Values

nodes

No

-

array of Node

-

-

Content

Name Required Description Type Format Allowable Values

type

No

-

string

-

-

value

No

-

string

-

-

Correlate

Inherits: InstrumentAction

Name Required Description Type Format Allowable Values

idExpression

No

-

string

-

-

CorrelationIdentifier

Name Required Description Type Format Allowable Values

scope

No

-

string

-

Interaction, ControlFlow, CausedBy

value

No

-

string

-

-

Deactivate

Inherits: InstrumentAction

EvaluateURIAction

Inherits: ProcessorAction

Name Required Description Type Format Allowable Values

template

No

-

string

-

-

Expression

Filter

Name Required Description Type Format Allowable Values

exclusions

No

-

array of string

-

-

inclusions

No

-

array of string

-

-

FreeFormAction

Inherits: InstrumentAction

Name Required Description Type Format Allowable Values

action

No

-

string

-

-

IgnoreNode

Inherits: InstrumentAction

InitiateCorrelation

Inherits: InstrumentAction

Name Required Description Type Format Allowable Values

idExpression

No

-

string

-

-

InstrumentAction

InstrumentBind

Name Required Description Type Format Allowable Values

expression

No

-

string

-

-

name

No

-

string

-

-

type

No

-

string

-

-

InstrumentComponent

Inherits: InstrumentAction

Name Required Description Type Format Allowable Values

componentTypeExpression

No

-

string

-

-

direction

No

-

string

-

In, Out

idExpression

No

-

string

-

-

operationExpression

No

-

string

-

-

uriExpression

No

-

string

-

-

InstrumentConsumer

Inherits: InstrumentAction

Name Required Description Type Format Allowable Values

direction

No

-

string

-

In, Out

endpointTypeExpression

No

-

string

-

-

idExpression

No

-

string

-

-

operationExpression

No

-

string

-

-

uriExpression

No

-

string

-

-

InstrumentProducer

Inherits: InstrumentAction

Name Required Description Type Format Allowable Values

direction

No

-

string

-

In, Out

endpointTypeExpression

No

-

string

-

-

idExpression

No

-

string

-

-

operationExpression

No

-

string

-

-

uriExpression

No

-

string

-

-

InstrumentRule

Name Required Description Type Format Allowable Values

notes

No

-

array of string

-

-

ruleName

No

-

string

-

-

Instrumentation

Name Required Description Type Format Allowable Values

compile

No

-

boolean

-

-

description

No

-

string

-

-

rules

No

-

array of InstrumentRule

-

-

InteractionNode

Inherits: ContainerNode

Name Required Description Type Format Allowable Values

in

No

-

Message

-

-

out

No

-

Message

-

-

Issue

Name Required Description Type Format Allowable Values

description

No

-

string

-

-

severity

No

-

string

-

Error, Warning, Info

JSONExpression

Inherits: Expression

Name Required Description Type Format Allowable Values

jsonpath

No

-

string

-

-

key

No

-

string

-

-

source

No

-

string

-

Content, Header

JVM

Inherits: InstrumentRule

Name Required Description Type Format Allowable Values

actions

No

-

array of InstrumentAction

-

-

binds

No

-

array of InstrumentBind

-

-

className

No

-

string

-

-

compile

No

-

boolean

-

-

condition

No

-

string

-

-

fromVersion

No

-

string

-

-

helper

No

-

string

-

-

interfaceName

No

-

string

-

-

location

No

-

string

-

-

methodName

No

-

string

-

-

parameterTypes

No

-

array of string

-

-

toVersion

No

-

string

-

-

LiteralExpression

Inherits: Expression

Name Required Description Type Format Allowable Values

value

No

-

string

-

-

Message

Name Required Description Type Format Allowable Values

content

No

-

object

-

-

headers

No

-

object

-

-

Node

Name Required Description Type Format Allowable Values

correlationIds

No

-

array of CorrelationIdentifier

-

-

duration

No

-

integer

int64

-

issues

No

-

array of Issue

-

-

operation

No

-

string

-

-

properties

No

-

array of Property

-

-

timestamp

No

-

integer

int64

-

type

No

-

string

-

Consumer, Producer, Component

uri

No

-

string

-

-

Percentiles

Name Required Description Type Format Allowable Values

percentiles

No

-

object

-

-

ProcessContent

Inherits: InstrumentAction

Name Required Description Type Format Allowable Values

direction

No

-

string

-

In, Out

valueExpressions

No

-

array of string

-

-

ProcessHeaders

Inherits: InstrumentAction

Name Required Description Type Format Allowable Values

direction

No

-

string

-

In, Out

headersExpression

No

-

string

-

-

originalType

No

-

string

-

-

Processor

Name Required Description Type Format Allowable Values

actions

No

-

array of ProcessorAction

-

-

description

No

-

string

-

-

direction

No

-

string

-

In, Out

faultFilter

No

-

string

-

-

nodeType

No

-

string

-

Consumer, Producer, Component

operation

No

-

string

-

-

predicate

No

-

Expression

-

-

uriFilter

No

-

string

-

-

ProcessorAction

Name Required Description Type Format Allowable Values

description

No

-

string

-

-

predicate

No

-

Expression

-

-

ProcessorIssue

Inherits: Issue

Name Required Description Type Format Allowable Values

action

No

-

string

-

-

field

No

-

string

-

-

processor

No

-

string

-

-

Producer

Inherits: InteractionNode

Name Required Description Type Format Allowable Values

endpointType

No

-

string

-

-

Property

Name Required Description Type Format Allowable Values

name

No

-

string

-

-

number

No

-

number

double

-

type

No

-

string

-

Text, Number, Boolean, Binary

value

No

-

string

-

-

SetLevel

Inherits: InstrumentAction

Name Required Description Type Format Allowable Values

levelExpression

No

-

string

-

-

SetProperty

Inherits: InstrumentAction

Name Required Description Type Format Allowable Values

name

No

-

string

-

-

valueExpression

No

-

string

-

-

SetPropertyAction

Inherits: ProcessorAction

Name Required Description Type Format Allowable Values

expression

No

-

Expression

-

-

name

No

-

string

-

-

type

No

-

string

-

Text, Number, Boolean, Binary

SetState

Inherits: InstrumentAction

Name Required Description Type Format Allowable Values

contextExpression

No

-

string

-

-

name

No

-

string

-

-

session

No

-

boolean

-

-

valueExpression

No

-

string

-

-

SetTraceId

Inherits: InstrumentAction

Name Required Description Type Format Allowable Values

valueExpression

No

-

string

-

-

SetTransaction

Inherits: InstrumentAction

Name Required Description Type Format Allowable Values

nameExpression

No

-

string

-

-

Suppress

Inherits: InstrumentAction

TextExpression

Inherits: Expression

Name Required Description Type Format Allowable Values

key

No

-

string

-

-

source

No

-

string

-

Content, Header

Trace

Name Required Description Type Format Allowable Values

fragmentId

No

-

string

-

-

hostAddress

No

-

string

-

-

hostName

No

-

string

-

-

nodes

No

-

array of Node

-

-

timestamp

No

-

integer

int64

-

traceId

No

-

string

-

-

transaction

No

-

string

-

-

TransactionConfig

Name Required Description Type Format Allowable Values

deleted

No

-

boolean

-

-

description

No

-

string

-

-

filter

No

-

Filter

-

-

lastUpdated

No

-

integer

int64

-

level

No

-

string

-

Ignore, None, All

processors

No

-

array of Processor

-

-

Inherits: InstrumentAction

XMLExpression

Inherits: Expression

Name Required Description Type Format Allowable Values

key

No

-

string

-

-

source

No

-

string

-

Content, Header

xpath

No

-

string

-

-