

Publish Custom Attributes With Analytics¶

Choreo Connect provides default set of attributes with the analytics data when an API invocation happens. In addition to that, users can add custom analytics data with an analytics event due to this feature. If there are specific request headers, response headers, and response trailers relevant to the event, users can retrieve those values and use them with Choreo Connect analytics. This guide will explain the steps required to do it.

Note

This feature is only available with ELK based Analytics. Only Request headers (headers sent to the upstream), Response headers (headers coming from the upstream), and Response trailers can be used with this feature.

Creating The Custom Analytics Data Provider JAR¶

You need to create a new Java Maven project to obtain this JAR.

There is an existing sample project available here. If you wish to use that sample instead of developing the sample from scratch, you can ignore the steps of creating the sample and start from here.

Configuring the pom.xml file¶

Add the wso2-nexus repository to the pom.xml file.

<repository>
    <id>wso2-nexus</id>
    <name>WSO2 internal Repository</name>
    <url>https://maven.wso2.org/nexus/content/groups/wso2-public/</url>
    <releases>
        <enabled>true</enabled>
        <updatePolicy>daily</updatePolicy>
        <checksumPolicy>ignore</checksumPolicy>
    </releases>
</repository>

2. Add relevant dependencies.

<dependency>
    <groupId>org.wso2.carbon.apimgt</groupId>
    <artifactId>org.wso2.carbon.apimgt.common.analytics</artifactId>
    <version>${carbon.apimgt.version}</version>
</dependency>

Info

You need to add org.wso2.carbon.apimgt.common.analytics_<COMPENENT_VERSION>.jar to the local m2 mannually and provide path to the local m2 as mentioned below.

Add the above .jar files to the local m2 manually.

mvn install:install-file -Dfile=<PATH_TO_FILE>/org.wso2.carbon.apimgt.common.analytics_<COMPENENT_VERSION>.jar -DgroupId=org.wso2.carbon.apimgt -DartifactId=org.wso2.carbon.apimgt.common.analytics -Dversion=<COMPENENT_VERSION> -Dpackaging=jar

Point local m2 repository in project pom

<repository>
    <id> local-maven-repo </id>
    <url> file://home/user/.m2/repository </url>
</repository>

Follow the same URL pattern when providing the repository URL.

Implementing the required class¶

AnalyticsCustomDataProvider Implementation Class¶

Analytics with custom attributes feature can be customized by implementing the AnalyticsCustomDataProvider interface. Therefore, it is required to implement a class from the AnalyticsCustomDataProvider interface. By overriding the getCustomProperties method it is possible to push custom analytics data. From Choreo Connect analytics implementation, all the header values (request, response headers, response trailers) relevant to the request will be sent in a HashMap. Therefore, by processing it you can obtain the required headers.

Build the project JAR addition to the Enforcer¶

Build the project using the following command.
```
mvn clean install
```
Obtain the relevant JAR from target folder and mount it to the {CC_HOME}/resources/enforcer/dropins folder.

Creating The Custom Reporter JAR to log analytics data¶

In order to log the custom attributes for the event occurrences, you need to add the Custom Reporter JAR to the dropins folder. You can follow the Step 1.1 explained here to obtain the JAR. Similar to the above after obtaining the JAR mount it to the enforcer/dropins folder.

Configure the log4j2.properties file with the following configurations.

Add a new logger to the Enforcer by adding the following configuration.

logger.org-wso2-analytics-publisher.name = org.wso2.am.analytics.publisher
logger.org-wso2-analytics-publisher.level = TRACE
logger.org-wso2-analytics-publisher.appenderRef.CARBON_TRACE_LOGFILE.ref = ENFORCER_ACCESS_LOG

Append the newly added logger as indicated below.

loggers = org-wso2-analytics-publisher, other_available_loggers...

Update the <CHOREO-CONNECT_HOME>/docker-compose/choreo-connect(-with-apim)/conf/config.toml file with the following configurations.

[analytics]
    enabled = true
    type = "ELK"
[analytics.adapter.customProperties]
    enabled = true
    requestHeaders = ["request_headers_to_pass_from_router_to_enforcer"]
    responseHeaders = ["response_headers_to_pass_from_router_to_enforcer"]
    responseTrailers = ["response_trailers_to_pass_from_router_to_enforcer"]
[analytics.enforcer]
    [analytics.enforcer.configProperties]
    "publisher.custom.data.provider.class" = "fully qualified class name of the customDataProvider"

Obtaining Custom Attributes with Analytics¶

Enable Choreo Connect analytics.
Initiate an event to publish analytics data.

In the Enforcer logs you will see the relevant attribute related to the API invocation under the properties field.

  choreo-connect-with-apim-enforcer-1  | ... Info -
  {
     "apiName":"TestAPI",
     "proxyResponseCode":401,
     "errorType":"AUTH",
     .
     .
     .
     "errorMessage":"AUTHENTICATION_FAILURE",
     "eventType":"fault",
     "regionId":"UNKNOWN",
     "applicationId":"UNKNOWN",
     "apiType":"HTTP",
     "properties":{
        "user-agent":"curl/7.83.0"
     }
  }

Top