Observe Ballerina Programs with New Relic
This article was written using Ballerina Swan Lake Update 8 (2201.8.0)
Ballerina is an open source, cloud-native programming language optimized for integration. It has the capability to let users observe application servers running in Ballerina.
Observability in Ballerina consists of the three major pillars below.
- Metrics: numeric values that are collected and aggregated over a period of time.
- Tracing: the activities that occur when a request/transaction occurs in the system from the point of entry to exit.
- Logging: text records of activities that occurred with relevant information along with the timestamp.
A complete guide on how to use observability in Ballerina is included in Observe Ballerina Programs.
This article focuses on how to observe Ballerina programs in New Relic, which is a Software as a Service offering that focuses on performance and availability monitoring. Users can observe metrics and traces in New Relic. Documentation is available on getting started with new relic about how to set up a new relic platform in your operating system.
The following steps will guide you to set up a Ballerina project to be observed with New Relic. I have used the Ballerina Swan Lake Update 8 (2201.8.0) version and can be downloaded from here.
Setup ballerina project
A new Ballerina project can be created by using the following command.
bal new <PROJECT_NAME>
Then a directory will be created which contains the Ballerina.toml file. By default, the following configuration will be added when you create a new project.
[build-options]
observabilityIncluded=trueIn this post,, the following simple HTTP service will be used.
import ballerina/http;
service /srvc on new http:Listener(8090) {
resource function get success() returns string|error {
return "successful";
}
}Observe Metrics in New Relic
To observe metrics in Ballerina programs, users need to configure publishing metrics and the metrics reporter in the Config.toml file, which should be created inside the project directory.
[ballerina.observe]
metricsEnabled=true
metricsReporter="prometheus"We use Prometheus as the metrics reporter since we cannot directly publish metrics into New Relic. Prometheus OpenMetrics integration can be done in two methods.
Here, we focus on using the Prometheus server as an intermediate metrics reporter, which will push the data to the New Relic server.
First, we need to set up a Ballerina program to publish data into the Prometheus server. We need to create a Config.toml file in the Ballerina project directory, which includes the following.
[ballerina.observe]
metricsEnabled=true
metricsReporter="prometheus"
[ballerinax.prometheus]
port=9797
host="0.0.0.0"Then include the following line into main bal file.
import ballerinax/prometheus;Please follow the documentation in observe metrics to find more details about how to observe Ballerina programs with Prometheus.
We need to push Prometheus data to the New Relic server via a remote write url. Remote write URL and the token can be generated from integrate Prometheus data. Documentation related to setting up Prometheus remote write integration can be found here.
Then we need to add the remote write URL and token into the prometheus.yml file where you run the Prometheus server.
remote_write:
- url: https://metric-api.newrelic.com/prometheus/v1/write?prometheus_server=<YOUR_DATA_SOURCE_NAME>
bearer_token: <TOKEN>When we run the sample Ballerina program given above, you can see the log given below.
ballerina: started Prometheus HTTP listener 0.0.0.0:9797Then send HTTP requests to the Ballerina service as given below.
curl http://localhost:8090/srvc/successYou can access the metrics that were published to the New Relic server in the New Relic query builder. You can view the metrics query data in graphical format, as shown below.
Observe Tracing in New Relic
Tracing information in Ballerina projects can be published to New Relic by using ballerinax zipkin package. It initially publishes tracing data into Zipkin server via a Zipkin Exporter, but it can be used to publish tracing information into different trace APIs as well.
There are two different tracing data formats that the New Relic trace API accepts to be published into their servers.
- Zipkin format
- New Relic format
- Open Telemetry format
We use Zipkin format for now since we are using the ballerinax/zipkin package in Ballerina. It has a Zipkin exporter, which uses HTTP protocol. The trace API used for the Zipkin data format is https://trace-api.newrelic.com/trace/v1. A trace API key is required to publish into New Relic servers. Please follow the path below to generate a trace API key.
Go to Profile -> API keys -> Insights Insert key -> Insert keys to create an account in New Relic.
For more information please refer to Trace API requirements.
We need to set up Ballerina program to publish tracing in Zipkin formatdata into the Zipkin server. We need to create a Config.toml file in the Ballerina project directory, which includes the following. Instead of host and port for Zipkin server, configure reporterEndpoint to pass trace API.
[ballerina.observe]
tracingEnabled=true
tracingProvider="zipkin"
[ballerinax.zipkin]
reporterEndpoint="https://trace-api.newrelic.com/trace/v1?Api-Key=<NEW_RELIC_LICENSE_KEY>&Data-Format=zipkin&Data-Format-Version=2"Then include the following line into main bal file.
import ballerinax/zipkin;When we run the sample Ballerina program given above, you can see the log given below.
ballerina: started publishing traces to Zipkin on https://trace-api.newrelic.com/trace/v1Then send HTTP requests to the Ballerina service as given below.
curl http://localhost:8090/srvc/successYou can access the traces that were published to the New Relic server in New Relic traces. You can view the metrics query data in graphical format, as shown below.
