Reporters are designed to record a variety of events occurring in the Gravitee API Management (APIM) Gateway and output them to a new source in their order of occurrence. This enables you to manage your data using a solution of your choice.
The following sections detail:
The following event types are supported:
| Type | Description |
|---|---|
request | This event type provides common request and response metrics, such as response time, application, request ID, and more. |
log | This event type provides more detailed request and response metrics. It is reported when logging has been enabled at the API level. |
health-check | This event type allows for health-check events to be reported when a health-check endpoint has been configured and enabled on an API. |
node | This event type provides some system and JVM metrics for the node Gravitee is running on. |
The following reporters are currently compatible with APIM:
| Type | Bundled in Distribution | Default | Enterprise only |
|---|---|---|---|
| Elasticsearch | true | true | false |
| File | true | false | false |
| TCP | true | false | true |
| Datadog | false | false | true |
{% hint style="warning" %} To learn more about Gravitee Enterprise and what's included in various enterprise packages, please:
Elasticsearch is the default reporter, but this section will show you how to configure different reporters. If you wish to use a reporter not included in the default distribution, you must first add the reporter as a plugin. Refer to the Plugins guide to learn more.
Configuration details for the Elasticsearch reporter are available in the Elasticsearch Repository documentation.
{% tabs %} {% tab title="Configuration parameters" %} The file reporter has the following configuration parameters:
| Parameter name | Description | Default value |
|---|---|---|
enabled | This setting determines whether the file reporter should be started or not. The default value is false. | false |
fileName | The path events should be written to. Use the %s-yyyy_mm_dd pattern to create one file per event type on a daily basis. | #{systemProperties['gravitee.home']}/metrics/%s-yyyy_mm_dd} |
output | Output file type - json, message_pack, elasticsearch, csv. | json |
flushInterval | File flush interval (in ms). | 1000 |
retainDays | The number of days to retain files before deleting one. | 0 (to retain forever) |
<EVENT_TYPE>.exclude | Fields to exclude from the output. Available for json and message_pack outputs only. | none |
<EVENT_TYPE>.include | Fields to include in the output. Available for json and message_pack outputs and only if excludes have been defined. | none |
<EVENT_TYPE>.rename | Fields to rename when writing the output. Available for json and message_pack outputs only. | none |
{% tab title="Example" %}
The configuration example below excludes all fields from the request JSON file except the api and application fields, renames the application field to app, and excludes log, node, and health-check events from being reported:
reporters:
file:
enabled: true
fileName: ${gravitee.home}/metrics/%s-yyyy_mm_dd
output: json
request:
exclude:
- "*"
include:
- api
- application
rename:
application: app
log:
exclude:
- "*"
node:
exclude:
- "*"
health-check:
exclude:
- "*"{% endtab %} {% endtabs %}
{% hint style="info" %}
<EVENT_TYPE> refers to the kind of event reported by the Gateway and can be either request, log, node or health-check. Fields referenced as exclude, include and rename items all support jsonPath for accessing nested elements.
{% endhint %}
{% tabs %} {% tab title="Configuration parameters" %} The file reporter has the following configuration parameters:
| Parameter name | Description | Default value |
|---|---|---|
enabled |
This setting determines whether the TCP reporter should be started or not. The default value is false. |
false |
output |
Format of the data written to the TCP socket - json, message_pack, elasticsearch, csv. | json |
host |
The TCP host where the event should be published. This can be a valid host name or an IP address. | localhost |
port |
The TCP port used to connect to the host. | 8123 |
connectTimeout |
Maximum time allowed to establish the TCP connection in milliseconds. | 10000 |
reconnectAttempts |
This setting determines how many times the socket should try to establish a connection in case of failure. | 10 |
reconnectInterval |
Time (in milliseconds) between socket connection attempts. | 500 |
retryTimeout |
If the max reconnect attempts have been reached, this setting determines how long (in milliseconds) the reporter should wait before trying to connect again. | 5000 |
tls.enabled |
Enable TLS | false |
tls.verifyClient |
If true, client certificate will be sent for mutual TLS negotiation. When enabling this, providing a key-store is required so that mutual TLS negotiation can happen. | false |
tls.keystore.type |
The type of key-store to use (either PEM, JKS or PFX) | null |
tls.keystore.password |
The password to use for the key-store (only for JKS and PFX types) | null |
tls.keystore.certs |
The list of certificates used, when type is PEM | null |
tls.keystore.keys |
The list of keys used, when type is PEM | null |
tls.truststore.type |
The type of trust-store to use (either PEM, JKS or PFX) | null |
tls.truststore.password |
The password to use for the trust-store (only for JKS and PFX types) | null |
tls.keystore.certs |
The list of certificates to trust, when type is PEM | null |
| {% endtab %} |
{% tab title="Example" %} The following example uses the same configuration as the file reporter example above, but writes the events to a TCP socket instead of a file:
reporters:
tcp:
enabled: true
host: localhost
port: 9001
output: json
request:
exclude:
- "*"
include:
- api
- application
rename:
application: app
log:
exclude:
- "*"
node:
exclude:
- "*"
health-check:
exclude:
- "*"
tls:
enabled: true
verifyClient: true
keystore:
type: pem
keys:
- client.key
certs:
- client.crt
truststore:
type: pem
certs:
- logstash.crt{% endtab %} {% endtabs %}
{% tabs %} {% tab title="Datadog conversions" %} This reporter allows you to send APIM Gateway events to Datadog listening server.
In the following table, you can see how different data from Gravitee has been transformed into the Datadog format.
| Gravitee | Datadog |
|---|---|
Monitor |
Metrics |
EndpointStatus |
Events |
Metrics |
Metrics |
Log |
Log |
| {% endtab %} |
{% tab title="Configuration parameters" %} The Datadog reporter has the following configuration parameters:
| Parameter name | Description | Default value |
|---|---|---|
enabled | This setting determines whether the Datadog reporter should be started or not. The default value is false. | false |
site | If you don’t use the default website of Datadog, for example if the data center is in the EU, then you need to set this variable. | null |
authentication | In order to send data to Datadog, you need to provide your Authentication details and all supported Datadog Authentication mechanisms can be used in here as well. You need to choose only one Authentication type and remove the rest. | N/A |
{% tab title="Example" %}
The configuration is loaded from the common APIM Gateway configuration file, gravitee.yml. This will send the data to your Datadog account:
reporters:
datadog:
enabled: true
site: "datadoghq.eu"
authentication:
#apiKeyPrefix: ""
apiKey: "YOUR_API_KEY"
#appKey: "YOUR_APP_KEY"
#tokenScheme: ""
#token: "YOUR_TOKEN"
#username: "YOUR_USERNAME"
#password: "YOUR_PASSWORD"{% endtab %} {% endtabs %}