reporters

Reporters

Overview

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:

• Supported event types
• Available reporters
• Reporter configurations

Event types

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.

Available reporters

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:

• Refer to the EE vs OSS documentation
• Book a demo
• Check out the pricing page {% endhint %}

Configuring reporters

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.

Elasticsearch reporter

Configuration details for the Elasticsearch reporter are available in the Elasticsearch Repository documentation.

File reporter

{% 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

{% endtab %}

{% 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 %}

TCP reporter

{% 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 %}

Datadog reporter

{% 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

{% endtab %}

{% 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 %}