Module observe
ballerina/observe
Module Overview
This module provides an API for observing Ballerina services. Ballerina supports Observability out of the box. This module provides an API to make observability more flexible for the Ballerina users.
To observe the Ballerina code, the '--b7a.observability.enabled=true' property should be given when starting the service (i.e., `ballerina run hello_world.bal --b7a.observability.enabled=true').
Tracing
Tracing provides information regarding the roundtrip of a service invocation based on the concept of spans, which are structured in a hierarchy based on the cause and effect concept. The tracing API allows users to tap into that tracing information, introduce new spans, and add additional information to existing spans using user-defined tags.
Samples
Start a root span & attach a child span
The following code snippet shows an example of starting a root span with no parent and starting another span as a child of the first span. Note: Make sure that all started spans are closed properly to ensure that all spans are reported properly.
Start a span attached to a system trace
When no parentSpanId is given or a parentSpanId of -1 is given, a span is started as a child span to the current active span in the ootb system trace.
Attach a tag to a span
It is possible to add tags to the span by using the observe:addTagToSpan() function by providing the span id and relevant tag key and tag value.
Attach a tag to a span in the system trace
When no spanId is provided or -1 is given, the defined tags are added to the current active span in the ootb system trace.
Metrics
There are mainly two kind of metrics instances supported; Counter and Gauge. A counter is a cumulative metric that represents a single monotonically increasing counter whose value can only increase or be reset to zero on restart. For example, you can use a counter to represent the number of requests served, tasks completed, or errors. The Gauge metric instance represents a single numerical value that can arbitrarily go up and down, and also based on the statistics configurations provided to the Gauge, it can also report the statistics such as max, min, mean, percentiles, etc.
Counter Samples
Create
The following code snippets provides the information on how Counter instances can be created. Instantiating the counter will simply create an instance based on the params passed.
Register
The counter can be registered with the global metrics registry. Therefore, it can be looked up later without having the reference of the counter that was created. Also, only the registered counters will be reported to the Metrics reporter such as Prometheus. In case, if there is already another non counter metric registered, then there will be an error returned. But if it's another counter instance, then the registered counter instance will be returned.
Unregister
The counter can be unregistered with the global metrics registry if it is already registered. If a metrics is unregistered, then further it'll not be included in metrics reporting.
Increment
The counter can be incremented without passing any params (defaulted to 1), or by a specific amount.
Reset
The counter can be resetted to default amount = 0.
Get Value
The current value can be retrieved by this operation.
Gauge Samples
Create
The following code snippets provides the information on how Gauge instances can be created. Instantiating the gauge will simply create an instance based on the params passed.
Register
The gauge can be registered with the global metrics registry, therefore it can be looked up later without having the reference of the gauge that was created. Also, only the registered counters will be reported to the Metrics reporter such as Prometheus. In case, if there is already another non gauge metric registered, then there will be an error returned. But if it's another gauge instance, then the registered gauge instance will be returned.
Unregister
The gauge can be unregistered with the global metrics registry if it is already registered. If a metrics is unregistered, then further it'll not be included in metrics reporting.
Increment
The gauge can be incremented without passing any params (defaulted to 1.0), or by a specific amount.
Decrement
The gauge can be decremented without passing any params (defaulted to 1.0), or by a specific amount.
Set Value
This method sets the gauge's value with specific amount.
Get Value
The current value can be retrieved by this operation.
Get Snapshot
This method retrieves current snapshot of the statistics calculation based on the configurations passed to the gauge. If the statistics are disabled, then it'll be returning nil ().
Global Metrics Samples
Get All Metrics
This method returns all the metrics that are registered in the global metrics registry. This method is mainly useful for metric reporters, where they can fetch all metrics, format those, and report.
Lookup Metric
This method will lookup for the metric from the global metric registry and return it.
Functions
addTagToMetrics
Add a key value pair as a tag to system metrics.
Return Type
- error? - An error if an error occurred while attaching tag to System Metrics
addTagToSpan
Add a key value pair as a tag to the span.
Parameters
- tagKey string - Key of the tag
- tagValue string - Value of the tag
- spanId int (default -1) - Id of span to which the tags should be added or -1 to add tags to the current active span
Return Type
- error? - An error if an error occurred while attaching tag to the span
finishSpan
Finish the current span.
Parameters
- spanId int - Id of span to finish
Return Type
- error? - An error if an error occurred while finishing the span
getAllMetrics
function getAllMetrics() returns Metric[]Retrieve all registered metrics including default metrics from the ballerina runtime, and user defined metrics.
Return Type
- Metric[] - Array of all registered metrics
getMetricsProvider
function getMetricsProvider() returns stringRetrieve metrics provider.
Return Type
- string - metrics provider.
getMetricsReporter
function getMetricsReporter() returns stringRetrieve metrics reporter.
Return Type
- string - metrics reporter.
getSpanContext
Retrieve a map of span context data.
getTracingProvider
function getTracingProvider() returns stringRetrieve tracer provider.
Return Type
- string - Tracing provider.
isMetricsEnabled
function isMetricsEnabled() returns booleanCheck whether metrics is enabled.
Return Type
- boolean - metrics enabled/disabled.
isObservabilityEnabled
function isObservabilityEnabled() returns booleanCheck whether observability is enabled.
Return Type
- boolean - observability enabled/disabled.
isTracingEnabled
function isTracingEnabled() returns booleanCheck whether tracing is enabled.
Return Type
- boolean - tracing enabled/disabled.
lookupMetric
Retrieve the specific metric that is described by the given name and tags.
Parameters
- name string - Name of the metric to lookup
startRootSpan
Start a span with no parent span.
Parameters
- spanName string - Name of the span
Return Type
- int - SpanId of the started span
startSpan
Start a span and create child relationship to current active span or user specified span.
Classes
observe: Counter
This represents the metric type - counter, that can be only increased by an integer number.
Constructor
This instantiates the Counter object. Name field is mandatory, and description and tags fields are optional and have its own default values when no params are passed.
init (string name, string? desc, map<string>? tags)register
function register() returns error?Register the counter metric instance with the Metric Registry.
Return Type
- error? - Returns error if there is any metric registered already with the same name but different parameters or in a different kind
unregister
function unregister()Unregister the counter metric instance with the Metric Registry.
increment
function increment(int amount)Increment the counter's value by an amount.
Parameters
- amount int (default 1) - The amount by which the value needs to be increased. The amount is defaulted as 1 and will be used if there is no amount passed in
reset
function reset()Resets the counter's value to zero.
getValue
function getValue() returns intRetrieves the counter's current value.
Return Type
- int - The current value of the counter
Fields
- name string - Name of the counter metric
- description string - Description of the counter metric
observe: Gauge
This represents the metric type - gauge, that can hold instantaneous, increased or decreased value during the usage.
Constructor
This instantiates the Gauge object. Name field is mandatory, and description, tags, and statitics config fields are optional and have its own default values when no params are passed.
init (string name, string? desc, map<string>? tags, StatisticConfig[]? statisticConfig)- name string - Name of the Gauge instance
- desc string? "" - Description of the Gauge instance. If no description is provided, the the default empty string will be used
- statisticConfig StatisticConfig[]? () - Statistics configurations array is used for statistics calculation. In case if empty statistics configurations array is passed, then statistics calculation will be disabled. If nil () is passed, then default statistics configs will be used for the statitics calculation
register
function register() returns error?Register the gauge metric instance with the Metric Registry.
Return Type
- error? - Returns error if there is any metric registered already with the same name but different parameters or in a different kind
unregister
function unregister()Unregister the counter metric instance with the Metric Registry.
increment
function increment(float amount)Increment the gauge's value by an amount.
Parameters
- amount float (default 1.0) - The amount by which the value of gauge needs to be increased. The amount is defaulted as 1.0 and will be used if there is no amount passed in
decrement
function decrement(float amount)Decrement the gauge's value by an amount.
Parameters
- amount float (default 1.0) - The amount by which the value of gauge needs to be decreased. The amount is defaulted as 1.0 and will be used if there is no amount passed in
setValue
function setValue(float amount)Sets the instantaneous value for gauge.
Parameters
- amount float - The instantaneous value that needs to be set as gauge value
getValue
function getValue() returns floatRetrieves the gauge's current value.
Return Type
- float - The current value of the gauge
getSnapshot
function getSnapshot() returns Snapshot[]?Retrieves statistics snapshots based on the statistics configs of the gauge.
Return Type
- Snapshot[]? - Array of the statistics snapshots. If there is no statisticsConfigs provided, then it will be nil
Fields
- name string - Name of the counter metric
- description string - Description of the counter metric
- statisticConfigs StatisticConfig[] - Array of StatisticConfig objects which defines about the statistical calculation of the gauge during its usage
Records
observe: Metric
This represents the generic metric record that can represent both counter and gauge.
Fields
- name string - Name of the metric
- desc string - Description of the metric
- metricType string - Type of the metric
- summary Snapshot[] - If the metric is configured with statistics config, then the calculated statistics of the metric
observe: PercentileValue
This represents the percentile value record.
Fields
- percentile float - The percentile of the reported value
- value float - The value of the percentile
observe: Snapshot
This represents the snapshot of the statistics calculation of the gauge.
Fields
- timeWindow int - The time window in which variation of the values are considered
- mean float - The average value within the time window
- max float - The max value within the time window
- min float - The min value within the time window
- stdDev float - The standard deviation value within the time window
- percentileValues PercentileValue[] - The percentiles values calculated wihtin the time window
observe: StatisticConfig
This represents the statistic configuration that can be used to instatiate gauge metric.
Fields
- percentiles float[] - The percentiles that needs to be calculated
- timeWindow int - The time window (in milli seconds) in which variation of the values are considered
- buckets int - The number of buckets used in the sliding time window
Annotations
observe: Observable
source functionThis is used for making a function observable. Can be applied to functions which are not observable by default to make them observable.