## Package Overview

The New Relic Observability Extension is one of the observability extensions in the <a target="_blank" href="https://ballerina.io/">Ballerina</a> language.

It provides an implementation for tracing and metrics and, publishing both metrics and traces to a <a target="_blank" href="https://newrelic.com/">New Relic</a> platform.

## Enabling New Relic Extension

To package the New Relic extension into the Jar, follow the following steps.
1. Add the following import to your program.
```ballerina
import ballerinax/newrelic as _;
```

2. Add the following to the `Ballerina.toml` when building your program.
```toml
[package]
org = "my_org"
name = "my_package"
version = "1.0.0"

[build-options]
observabilityIncluded=true
```

To enable the extension and publish traces and metrics to New Relic, add the following to the `Config.toml` when running your program.

```toml
[ballerina.observe]
tracingEnabled=true
tracingProvider="newrelic"
metricsEnabled=true
metricsReporter="newrelic"

[ballerinax.newrelic]
apiKey="<NEW_RELIC_LICENSE_KEY>"    # Mandatory Configuration.
tracingSamplerType="const"          # Optional Configuration. Default value is 'const'
tracingSamplerParam=1               # Optional Configuration. Default value is 1
tracingReporterFlushInterval=15000  # Optional Configuration. Default value is 15000 milliseconds
tracingReporterBufferSize=10000     # Optional Configuration. Default value is 10000
metricReporterFlushInterval=15000   # Optional Configuration. Default value is 15000 milliseconds
metricReporterClientTimeout=10000   # Optional Configuration. Default value is 10000 milliseconds
```

User can configure the environment variable `BALLERINA_NEWRELIC_API_KEY` instead of `apiKey` in `Config.toml`.
If both are configured, `apiKey` in `Config.toml` will be overwritten by the environment variable value.

### Observe Metrics in New Relic

Instead of using prometheus as an intermediate metric reporter that remote writes the metrics to New Relic,
Ballerina New Relic Observability Extension directly publishes metrics to New Relic on the following metric API `https://metric-api.newrelic.com/metric/v1`.

Instrumentation of metrics is done using the [com.newrelic.telemetry](https://github.com/newrelic/newrelic-telemetry-sdk-java).

#### Available Metrics

The exporter provides the following metrics.

|Metric Name|Description|
|---|---|
|response_time_seconds_value|Response time of a HTTP request in seconds|
|response_time_seconds_max|Maximum response time of a HTTP request|
|response_time_seconds_min|Minimum response time of a HTTP request|
|response_time_seconds_mean|Average response time of a HTTP request|
|response_time_seconds_stdDev|Standard deviation of response time of a HTTP request|
|response_time_seconds|Summary of HTTP request-response times across various time frames and quantiles|
|response_time_nanoseconds_total_value|Response time of a HTTP request in nano seconds|
|requests_total_value|Total number of requests|
|response_errors_total_value|Total number of response errors|
|inprogress_requests_value|Total number of inprogress requests|
|kafka_publishers_value|Number of publishers in kafka|
|kafka_consumers_value|Number of consumers in kafka|
|kafka_errors_value|Number of errors happened while publishing in kafka|

### Observe Traces in New Relic

Ballerina New Relic Observability Extension directly publishes traces to New Relic on the following trace API `https://otlp.nr-data.net:4317`.
Traces are published to New Relic on OpenTelemetry format.

Instrumentation of traces is done using the [io.opentelemetry](https://github.com/open-telemetry/opentelemetry-java) and `GRPC` protocol is used send traces.


The New Relic Observability Extension is one of the observability extensions in the <a target="_blank" href="https://ballerina.io/">Ballerina</a> language.


newrelic

The New Relic Observability Extension is one of the observability extensions in the <a target="_blank" href="https://ballerina.io/">Ballerina</a> language.

observe

@cloud:Expose annotation marks a port that has to be exposed in a custom listener initializer.
```ballerina
public function init(@cloud:Expose int port) {}
```


@cloud:Task annotation to configure cron job.


The annotation, which is used for the constraints of the `anydata[]` type.


The annotation, which is used for the constraints of the `Date` type, which is structurally equivalent
to the following record:
```ballerina
type Date record {
   int year;
   int month;
   int day;
};
```
This annotation will enable validation on the date fields in the record. Additionally,
the `option` field can be used to validate the date against the provided option.


The annotation, which is used for the constraints of the `float` type.


The annotation, which is used for the constraints of the `int` type.


The annotation, which is used for the constraints of the `int`, `float`, and `decimal` types.


The annotation, which is used for the constraints of the `string` type.


Represents the annotation of the ID type.


The annotation to configure a GraphQL interceptor.


The annotation to configure a GraphQL resolver.


The annotation to configure a GraphQL service.


The annotation to designate a GraphQL object type as a federated entity.


The annotation to designate a GraphQL service as a federated GraphQL subgraph.


The annotation which is used to configure a gRPC service.


The annotation which is used to define the response cache configuration. This annotation only supports `anydata` and
Success(2XX) `StatusCodeResponses` return types. Default annotation adds `must-revalidate,public,max-age=3600` as
`cache-control` header in addition to `etag` and `last-modified` headers.


The annotation which is used to configure the type of the response.


The annotation which is used to define the Header resource signature parameter.


The annotation which is used to define the Payload resource signature parameter and return parameter.


The annotation which is used to define the query resource signature parameter.


The annotation which is used to configure an HTTP resource.


The annotation which is used to configure an HTTP service.


Describes the Java class representing a Ballerina binding.
```ballerina
@java:Binding {
  'class: "java.io.File"
}
```


Describes a Java constructor, which provides an implementation of a Ballerina function of which the body is marked as
`external`. If the Ballerina function body is marked as `external`, it means that the implementation of the
function is not provided in the Ballerina source module.

The following code snippet shows an example usage of this annotation. Here, the `newJavaLinkedList` Ballerina function's
implementation is provided by the default constructor of the `java.util.LinkedList` class.
```ballerina
function newJavaLinkedList() returns handle = @java:Constructor {
     'class: "java.util.LinkedList"
} external;
```


Describes a Java Field access, which provides an implementation of a Ballerina function of which the body is marked as
`external`.
```ballerina
function getError() returns handle = @java:FieldGet {
    name:"err",
    'class:"java/lang/System"
} external;
```


Describes a Java Field mutate, which provides an implementation of a Ballerina function of which the body is marked as
`external`.
```ballerina
function setContractId(handle contractId) = @java:FieldSet {
  name:"contractId",
  'class:"org/lang/impl/JavaFieldAccessMutate"
} external;
```


Describes a Java method, which provides an implementation of a Ballerina function of which the body is marked as
`external`. If the Ballerina function body is marked as `external`, it means that the implementation of the
function is not provided in the Ballerina source module.

The following code snippet shows an example usage of this annotation. Here, the `getUUID` Ballerina function's
implementation is provided by the `java.util.UUID.randomUUID` static method.
```ballerina
function getUUID() returns handle = @java:Method {
    name: "randomUUID",
    'class: "java.util.UUID"
} external;
```
The `name` field is optional. If it is not provided, the name of the Java method is inferred
from the Ballerina function.


This is used for making a function observable.
Can be applied to functions which are not observable by default to make them observable.



Annotation for additional OpenAPI information of a Ballerina service.


The Annotation used to specify which database column matches the Typed record field.


Identifies test factory function for dynamic test registration.
Identifies beforeSuite function.


The annotation which is used to configure local transaction participant function.


The annotation which is used to configure a WebSocket service.


WebSub Subscriber Configuration for the service, indicating subscription related parameters.


WebSub Hub Configuration for the service.


The annotation is used to denote the field that is considered an attribute.
In the XML-record conversion, this annotation can be used to add XML attribute using the `xmldata:toXML` API and
validate the XML attribute with record fields in the `xmldata:fromXml` API.


The annotation is used to specify the new name of the existing record name or field name according to the XML format.
In the XML-record conversion, this annotation can be used to override the default XML element name using the
`xmldata:toXML` API and validate the overridden XML element name with record field using the `xmldata:fromXml` API.


The annotation is used to specify the namespace's prefix and URI of the XML element.
In the XML-record conversion, this annotation can be used to add XML namespace using the `xmldata:toXML` API and
validate the the XML namespace with record in the `xmldata:fromXml` API.


Represents the client Basic Auth provider, which is used to authenticate with an external endpoint by generating a
Basic Auth token against the provided credential configurations.
```ballerina
auth:CredentialsConfig config = {
    username: "tom",
    password: "123"
}
auth:ClientBasicAuthProvider provider = new(config);
```


Represents the file user store based listener Basic Auth provider, which is used to authenticate the provided
credentials against the provided file user store configurations.
```ballerina
auth:ListenerFileUserStoreBasicAuthProvider provider = new;
```
The users are denoted by a section in the `Config.toml` file. The username, password, and the scopes of a particular
user are denoted as keys under the users section as shown below. For multiple users, the complete section has to be
duplicated.
```
[[ballerina.auth.users]]
username = "alice"
password = "password1"
scopes = ["scope1", "scope2"]
```


Represents the LDAP-based listener Basic Auth provider, which is used to authenticate the provided credentials
against the provided LDAP user store configurations. This connects to an active directory or an LDAP, retrieves
the necessary user information, and performs authentication and authorization.
```ballerina
auth:LdapUserStoreConfig config = {
    domainName: "ballerina.io",
    connectionURL: "ldap://localhost:389",
    connectionName: "cn=admin,dc=avix,dc=lk"
};
auth:ListenerLdapUserStoreBasicAuthProvider provider = new(config);
```


The `cache:Cache` object, which is used for all the cache-related operations. It is not recommended to insert `()`
as the value of the cache since it doesn't make any sense to cache a nil.


The GraphQL context object used to pass the meta information between resolvers.


Represents the information about a particular field of a GraphQL document.


Represents a default implementation of the DataLoader.


Defines the Basic Auth handler for client authentication.


Defines the Bearer token auth handler for client authentication.


Defines the self signed JWT handler for client authentication.


Defines the file store Basic Auth handler for listener authentication.


Defines the JWT auth handler for listener authentication.


Represents a default persistent cookie handler, which stores persistent cookies in a CSV file.



Represents the headers of the inbound request.


Implements a cache for storing HTTP responses. This cache complies with the caching policy set when configuring
HTTP caching in the HTTP client endpoint.



Represents a 'future' that returns as a result of an asynchronous HTTP request submission.
This can be used as a reference to fetch the results of the submission.


Implementation of round robin load balancing strategy.



Represents an HTTP/2 `PUSH_PROMISE` frame.



Configures the cache control directives for an `http:Request`.



Represents an HTTP Context that allows user to pass data between interceptors.


Configures cache control directives for an `http:Response`.



Represents the status code of `STATUS_ACCEPTED`.



Represents the status code of `STATUS_ALREADY_REPORTED`.



Represents the status code of `STATUS_BAD_GATEWAY`.



Represents the status code of `STATUS_BAD_REQUEST`.



Represents the status code of `STATUS_CONFLICT`.



Represents the status code of `STATUS_CONTINUE`.



Represents the status code of `STATUS_CREATED`.



Represents the status code of `STATUS_EARLY_HINTS`.



Represents the status code of `STATUS_EXPECTATION_FAILED`.



Represents the status code of `STATUS_FAILED_DEPENDENCY`.



Represents the status code of `STATUS_FORBIDDEN`.



Represents the status code of `STATUS_FOUND`.



Represents the status code of `STATUS_GATEWAY_TIMEOUT`.



Represents the status code of `STATUS_GONE`.



Represents the status code of `STATUS_HTTP_VERSION_NOT_SUPPORTED`.



Represents the status code of `STATUS_IM_USED`.



Represents the status code of `STATUS_INSUFFICIENT_STORAGE`.



Represents the status code of `STATUS_INTERNAL_SERVER_ERROR`.



Represents the status code of `STATUS_LENGTH_REQUIRED`.



Represents the status code of `STATUS_LOCKED`.



Represents the status code of `STATUS_LOOP_DETECTED`.



Represents the status code of `STATUS_METHOD_NOT_ALLOWED`.



Represents the status code of `STATUS_MISDIRECTED_REQUEST`.



Represents the status code of `STATUS_MOVED_PERMANENTLY`.



Represents the status code of `STATUS_MULTIPLE_CHOICES`.



Represents the status code of `STATUS_MULTI_STATUS`.



Represents the status code of `STATUS_NETWORK_AUTHENTICATION_REQUIRED`.



Represents the status code of `STATUS_NO_CONTENT`.



Represents the status code of `STATUS_NON_AUTHORITATIVE_INFORMATION`.



Represents the status code of `STATUS_NOT_ACCEPTABLE`.



Represents the status code of `STATUS_NOT_EXTENDED`.



Represents the status code of `STATUS_NOT_FOUND`.



Represents the status code of `STATUS_NOT_IMPLEMENTED`.



Represents the status code of `STATUS_NOT_MODIFIED`.



Represents the status code of `STATUS_OK`.



Represents the status code of `STATUS_PARTIAL_CONTENT`.



Represents the status code of `STATUS_PAYLOAD_TOO_LARGE`.



Represents the status code of `STATUS_PAYMENT_REQUIRED`.



Represents the status code of `STATUS_PERMANENT_REDIRECT`.



Represents the status code of `STATUS_PRECONDITION_FAILED`.



Represents the status code of `STATUS_PRECONDITION_REQUIRED`.



Represents the status code of `STATUS_PROCESSING`.



Represents the status code of `STATUS_PROXY_AUTHENTICATION_REQUIRED`.



Represents the status code of `STATUS_RANGE_NOT_SATISFIABLE`.



Represents the status code of `STATUS_REQUEST_HEADER_FIELDS_TOO_LARGE`.



Represents the status code of `STATUS_REQUEST_TIMEOUT`.



Represents the status code of `STATUS_RESET_CONTENT`.



Represents the status code of `STATUS_SEE_OTHER`.



Represents the status code of `STATUS_SERVICE_UNAVAILABLE`.



Represents the status code of `STATUS_SWITCHING_PROTOCOLS`.



Represents the status code of `STATUS_TEMPORARY_REDIRECT`.



Represents the status code of `STATUS_TOO_EARLY`.



Represents the status code of `STATUS_TOO_MANY_REQUESTS`.



Represents the status code of `STATUS_UNAUTHORIZED`.



Represents the status code of `STATUS_UNAVAILABLE_DUE_TO_LEGAL_REASONS`.



Represents the status code of `STATUS_UNPROCESSABLE_ENTITY`.



Represents the status code of `STATUS_UNSUPPORTED_MEDIA_TYPE`.



Represents the status code of `STATUS_UPGRADE_REQUIRED`.



Represents the status code of `STATUS_URI_TOO_LONG`.



Represents the status code of `STATUS_USE_PROXY`.



Represents the status code of `STATUS_VARIANT_ALSO_NEGOTIATES`.



Represents an IMAP Client, which interacts with an IMAP Server.


Represents a POP Client, which interacts with a POP Server.


Represents an SMTP Client, which interacts with an SMTP Server.


Represents an FTP caller that is passed to the onFileChange function


Represents an FTP client that intracts with an FTP server


The Ballerina GraphQL client that can be used to communicate with GraphQL APIs.


The base client used in the generated client code to provide remote functions for interacting with the caller.



The base client used in the generated client code to provide the capability for initiating the contact and executing remote calls with a remote gRPC service.


Defines the OAuth2 handler for client authentication.


Defines the LDAP store Basic Auth handler for listener authentication.


Defines the OAuth2 handler for listener authentication.


This is used for internal purposes to support reflection.


The base client used in the generated client code to provide the gRPC streaming client actions for
interacting  with the gRPC server.


The caller actions for responding to client requests.



The HTTP client provides the capability for initiating contact with a remote HTTP service. The API it
provides includes the functions for the standard HTTP methods forwarding a received request and sending requests
using custom HTTP verbs.


An HTTP client endpoint which provides failover support over multiple HTTP clients.



LoadBalanceClient endpoint provides load balancing functionality over multiple HTTP clients.



Represents the client that is used to complete received messages.


Represents the client that is used to publish messages to the server.


Represents caller object in tcp service remote methods.



Initializes the TCP connection client based on the provided configurations.


Represents caller object in UDP service remote methods.



Initializes the UDP connectionless client based on the provided configurations.


Initializes the UDP connection oriented client based on the 
provided configurations.


Represents a WebSocket synchronous client endpoint.


Represents resource-discovery service which identify the `hub` and `topic` from `resource-URL`.


The HTTP based client for WebSub subscription and unsubscription.


HTTP Based client for WebSub content publishing to subscribers


The HTTP based client for WebSub topic registration and deregistration, and notifying the hub of new updates.


The `OAEPWithSHA256AndMGF1` padding mode.


The `OAEPwithSHA384andMGF1` padding mode.


The `OAEPwithSHA512andMGF1` padding mode.


The prefix used to denote the Basic authentication scheme.


The prefix used to denote the Bearer authentication scheme.


Always set accept-encoding/content-encoding in outbound request/response.


When service behaves as a HTTP gateway inbound request/response accept-encoding option is set as the
outbound request/response accept-encoding/content-encoding option.


Never set accept-encoding/content-encoding header in outbound request/response.


Define _Any Scalar type used in subgraph schema.


Represents the Authorization header name.


HTTP header key `age`. Gives the current age of a cached HTTP response. 


HTTP header key `cache-control`. Specifies the cache control directives required for the function of HTTP caches.


This is a more restricted mode of RFC 7234. Setting this as the caching policy restricts caching to instances
where the `cache-control` header and either the `etag` or `last-modified` header are present.


Represents the closed state of the circuit. When the Circuit Breaker is in `CLOSED` state, all requests will be
allowed to go through to the upstream service. If the failures exceed the configured threhold values, the circuit
will trip and move to the `OPEN` state.


Represents the half-open state of the circuit. When the Circuit Breaker is in `HALF_OPEN` state, a trial request
will be sent to the upstream service. If it fails, the circuit will trip again and move to the `OPEN` state. If not,
it will move to the `CLOSED` state.


Represents the open state of the circuit. When the Circuit Breaker is in `OPEN` state, requests will fail
immediately.


Always set chunking header in the response.


If the payload is less than 8KB, content-length header is set in the outbound request/response,
otherwise chunking header is set in the outbound request/response.}


Never set the chunking header even if the payload is larger than 8KB in the outbound request/response.


HTTP header key `connection`. Allows the sender to specify options that are desired for that particular connection.


HTTP header key `content-length`. Specifies the size of the response body in bytes. 


HTTP header key `content-type`. Specifies the type of the message payload. 


HTTP header key `date`. The timestamp at the time the response was generated/received. 


Constant for the default listener gracefulStop timeout in seconds


Constant for the default listener endpoint timeout in seconds


HTTP header key `etag`. A finger print for a resource which is used by HTTP caches to identify whether a
resource representation has changed.


HTTP header key `expect`. Specifies expectations to be fulfilled by the server. 


HTTP header key `expires`. Specifies the time at which the response becomes stale. 


Constant for the identify not an HTTP Operation


HTTP header key `if-modified-since`. Used when validating (with the origin server) whether a cached response
is still valid. If the representation of the resource has modified since the timestamp in this field, a
304 response is returned.


HTTP header key `if-none-match`. Used when validating (with the origin server) whether a cached response is
still valid. If the ETag provided in this field matches the representation of the requested resource, a
304 response is returned.


Constant to get the jwt information from the request context.


Keeps the connection alive irrespective of the `connection` header value }


Decides to keep the connection alive or not based on the `connection` header of the client request }


Closes the connection irrespective of the `connection` header value }


HTTP header key `last-modified`. The time at which the resource was last modified. 


Header is placed before the payload of the request/response.


HTTP header key `location`. Indicates the URL to redirect a request to. 


When used in requests, `max-age` implies that clients are not willing to accept responses whose age is greater
than `max-age`. When used in responses, the response is to be considered stale after the specified
number of seconds.


Indicates that the client is willing to accept responses which have exceeded their freshness lifetime by no more
than the specified number of seconds.


Setting this as the `max-stale` directives indicates that the `max-stale` directive does not specify a limit.


Indicates that the client is only accepting responses whose freshness lifetime >= current age + min-fresh.


Indicates that once the response has become stale, it should not be reused for subsequent requests without
validating with the origin server.


Forces the cache to validate a cached response with the origin server before serving.


Instructs the cache to not store a response in non-volatile storage.


Instructs intermediaries not to transform the payload.


Indicates that the client is only willing to accept a cached response. A cached response is served subject to
other constraints posed by the request.


Metric Name	Description
response_time_seconds_value	Response time of a HTTP request in seconds
response_time_seconds_max	Maximum response time of a HTTP request
response_time_seconds_min	Minimum response time of a HTTP request
response_time_seconds_mean	Average response time of a HTTP request
response_time_seconds_stdDev	Standard deviation of response time of a HTTP request
response_time_seconds	Summary of HTTP request-response times across various time frames and quantiles
response_time_nanoseconds_total_value	Response time of a HTTP request in nano seconds
requests_total_value	Total number of requests
response_errors_total_value	Total number of response errors
inprogress_requests_value	Total number of inprogress requests
kafka_publishers_value	Number of publishers in kafka
kafka_consumers_value	Number of consumers in kafka
kafka_errors_value	Number of errors happened while publishing in kafka

ballerinax/newrelic Ballerina library

Package Overview

Enabling New Relic Extension

Observe Metrics in New Relic

Available Metrics

Observe Traces in New Relic