Skip to content

Commit cafe1f5

Browse files
karenc-bqkarenc-bq
authored
docs: update telemetry documentation (#972)
1 parent e7037be commit cafe1f5

File tree

1 file changed

+38
-43
lines changed

1 file changed

+38
-43
lines changed

‎docs/using-the-jdbc-driver/Telemetry.md‎

Lines changed: 38 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -42,7 +42,7 @@ Before enabling the Telemetry feature, a few setup steps are required to ensure
4242
4343
## Using Telemetry
4444

45-
Telemetry for the AWS JDBC Driver is a monitoring strategy that overlooks all plugins enabled in [`wrapperPlugins`](../UsingTheJdbcDriver.md#connection-plugin-manager-parameters) and is not a plugin in itself. Therefore no changes are required in the `wrapperPlugins` parameter to enable Telemetry.
45+
Telemetry for the AWS JDBC Driver is a monitoring strategy that overlooks all plugins enabled in [`wrapperPlugins`](./UsingTheJdbcDriver.md#connection-plugin-manager-parameters) and is not a plugin in itself. Therefore no changes are required in the `wrapperPlugins` parameter to enable Telemetry.
4646

4747
In order to enable Telemetry in the AWS JDBC Driver, you need to:
4848

@@ -73,17 +73,17 @@ OpenTelemetrySdk.builder()
7373
.buildAndRegisterGlobal();
7474
```
7575

76-
We also provide a [complete sample application](examples/AWSDriverExample/src/main/java/software/amazon/TelemetryMetricsOTLPExample.java) using telemetry in the examples folder of this repository.
76+
We also provide a [complete sample application](../../examples/AWSDriverExample/src/main/java/software/amazon/TelemetryMetricsOTLPExample.java) using telemetry in the examples folder of this repository.
7777

7878
### Telemetry Parameters
7979
In addition to the parameter that enables Telemetry, you can pass following parameters to the AWS JDBC Driver through the connection URL to configure how telemetry data will be forwarded.
8080

81-
| Parameter | Value | Required | Description | Default Value |
82-
|---|:---:|:---:|:---|---|
83-
| `enableTelemetry` | Boolean | No | Telemetry will be enabled when this property is set to `true`, otherwise no telemetry data will be gathered during the execution of the wrapper. | `false` |
84-
| `telemetryTracesBackend` | String | No | Determines to which backend the gathered tracing data will be forwarded to. Possible values include: `NONE`, `XRAY`, and `OTLP`.<br>`NONE` indicates that the application will collect tracing data but this data will not be forwarded anywhere.<br>`XRAY` indicates that the traces will be collected by the AWS XRay Daemon.<br>`OTLP` indicates that the traces will be collected by the AWS OTEL COllector. | `NONE` |
85-
| `telemetryMetricsBackend` | String | No | Determines to which backend the gathered metrics data will be forwarded to. Possible values include: `NONE` and `OTLP`.<br>`NONE` indicates that the application will collect metrics data but this data will not be forwarded anywhere.<br>`OTLP` indicates that the metrics will be collected by the AWS OTEL COllector. | `NONE` |
86-
| `telemetrySubmitTopLevel` | String | No | Determines which nesting strategy to adopt for traces about top level traces and nested traces.<br><br>See the [Nested tracing strategies using Amazon XRay](#Nested-Tracing-Strategies-Using-Amazon-XRay) section for more details about nesting strategies.<br><br>`ALWAYS_TOP_LEVEL` means that every JDBC call to the driver will generate a trace with no direct parent trace attached to it. If there is already an open trace being recorded by the application, no driver traces will be created.<br>`ALWAYS_NESTED` means that the wrapper will assume that there is an open trace in the application and the driver traces will all be attached to that open trace. If the user selects this value for the property and there is no open trace in the user application, no trace will be created.<br>`TOP_LEVEL` means that the application will look if there is an open trace in the users application prior to record telemetry data. If there is a current open trace, the traces created will be attached to that open trace. If not, all telemetry traces created will be top level.<br>`NO_TRACE` means that no traces will be created during the wrapper execution. | `TOP_LEVEL` |
81+
| Parameter | Value | Required | Description | Default Value |
82+
|---------------------------|:-------:|:--------:|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------|
83+
| `enableTelemetry` | Boolean | No | Telemetry will be enabled when this property is set to `true`, otherwise no telemetry data will be gathered during the execution of the wrapper. | `false` |
84+
| `telemetryTracesBackend` | String | No | Determines to which backend the gathered tracing data will be forwarded to. Possible values include: `NONE`, `XRAY`, and `OTLP`.<br>`NONE` indicates that the application will collect tracing data but this data will not be forwarded anywhere.<br>`XRAY` indicates that the traces will be collected by the AWS XRay Daemon.<br>`OTLP` indicates that the traces will be collected by the AWS OTEL COllector. | `NONE` |
85+
| `telemetryMetricsBackend` | String | No | Determines to which backend the gathered metrics data will be forwarded to. Possible values include: `NONE` and `OTLP`.<br>`NONE` indicates that the application will collect metrics data but this data will not be forwarded anywhere.<br>`OTLP` indicates that the metrics will be collected by the AWS OTEL COllector. | `NONE` |
86+
| `telemetrySubmitTopLevel` | Boolean | No | By default the driver will look for open traces in the users application prior to record telemetry data. If there is a current open trace, the traces created will be attached to that open trace. If not, all telemetry traces created will be top level. Setting the parameter to `false` means that every JDBC call to the driver will generate a trace with no direct parent trace attached to it. If there is already an open trace being recorded by the application, no driver traces will be created. See the [Nested tracing strategies section](#nested-tracing-strategies-using-amazon-xray) for more information. | `false` |
8787

8888
## Nested tracing strategies using Amazon XRay
8989

@@ -103,13 +103,8 @@ When a trace is hierarchically linked to a parent trace, we say that this trace
103103

104104
Applications that interact with the AWS JDBC Driver may or may not have already opened telemetry traces on their own. In this case, it is up to the user to determine how they want to mix both application and driver traces.
105105

106-
This can be done using the AWS JDBC Driver's `telemetrySubmitTopLevel` property. This property allows users to choose to submit the driver traces always as top level traces, to submit them nested to the application traces, or even to not submit the driver traces at all.
107-
108-
The `telemetrySubmitTopLevel` property allows 4 different options to choose from:
109-
- `ALWAYS_TOP_LEVEL` means that all the driver traces should be all forced into being top level traces. If the application has already open traces, it will not be possible for the driver traces to be top level and the driver traces therefore will not be submitted.
110-
- `ALWAYS_NESTED` indicates that the user wants the driver traces to always be nested into their application traces. That will happen unless there are no open application traces when the driver is running. In that case no driver traces will be collected or submitted.
111-
-`TOP_LEVEL` is a strategy where driver traces are submitted as top level traces, unless there is already an application open trace. If there is already an open trace, the driver traces will identify it and be submitted as nested traces with the application trace as parent.
112-
- `NO_TRACE` indicates that no traces will be submitted to Amazon XRay.
106+
This can be done using the AWS JDBC Driver's `telemetrySubmitTopLevel` property. This property allows users to choose to submit the driver traces always as top level traces or to submit them nested to the application traces.
107+
The default value is set to `false`, which means the driver traces to always be nested into their application traces. That will happen unless there are no open application traces when the driver is running. In that case no driver traces will be collected or submitted. When the property is set to `true`, all the driver traces would be submitted top level traces. If the application has already open traces, it will not be possible for the driver traces to be top level and the driver traces therefore will not be submitted.
113108

114109
## List of Metrics
115110

@@ -119,46 +114,46 @@ Metrics can be one of 3 types: counters, gauges or histograms.
119114

120115
### EFM plugin
121116

122-
| Metric name | Metric type | Description |
123-
|---|---|---|
124-
| efm.connections.aborted | Counter | Number of times a connection was aborted after being defined as unhealthy by an EFM monitoring thread |
125-
| efm.nodeUnhealthy.count.[NODE] | Counter | Number of times a specific node has been defined as unhealthy |
117+
| Metric name | Metric type | Description |
118+
|--------------------------------|-------------|-------------------------------------------------------------------------------------------------------|
119+
| efm.connections.aborted | Counter | Number of times a connection was aborted after being defined as unhealthy by an EFM monitoring thread |
120+
| efm.nodeUnhealthy.count.[NODE] | Counter | Number of times a specific node has been defined as unhealthy |
126121

127122
### Secrets Manager plugin
128123

129-
| Metric name | Metric type | Description |
130-
|---|---|---|
131-
| secretsManager.fetchCredentials.count | Counter | Number of times credentials were fetched from Secrets Manager |
124+
| Metric name | Metric type | Description |
125+
|---------------------------------------|-------------|---------------------------------------------------------------|
126+
| secretsManager.fetchCredentials.count | Counter | Number of times credentials were fetched from Secrets Manager |
132127

133128
### IAM plugin
134129

135-
| Metric name | Metric type | Description |
136-
|---|---|---|
137-
| iam.fetchToken.count | Counter | Number of times tokens were fetched from IAM |
138-
| iam.tokenCache.size | Gauge | Size of the token cache |
130+
| Metric name | Metric type | Description |
131+
|----------------------|-------------|----------------------------------------------|
132+
| iam.fetchToken.count | Counter | Number of times tokens were fetched from IAM |
133+
| iam.tokenCache.size | Gauge | Size of the token cache |
139134

140135
### Data Cache plugin
141136

142-
| Metric name | Metric type | Description |
143-
|---|---|---|
144-
| dataCache.cache.hit | Counter | Number of times the cache was consulted and found a cached entry |
145-
| dataCache.cache.miss | Counter | Number of times the cacbe was consulted and no match was found |
146-
| dataCache.cache.totalCalls | Counter | Total number of calls to the cache |
147-
| dataCache.cache.size | Gauge | Size of the data cache |
137+
| Metric name | Metric type | Description |
138+
|----------------------------|-------------|------------------------------------------------------------------|
139+
| dataCache.cache.hit | Counter | Number of times the cache was consulted and found a cached entry |
140+
| dataCache.cache.miss | Counter | Number of times the cacbe was consulted and no match was found |
141+
| dataCache.cache.totalCalls | Counter | Total number of calls to the cache |
142+
| dataCache.cache.size | Gauge | Size of the data cache |
148143

149144
### Failover plugin
150145

151-
| Metric name | Metric type | Description |
152-
|---|---|---|
153-
| writerFailover.triggered.count | Counter | Number of times writer failover was triggered |
154-
| writerFailover.completed.success.count | Counter | Number of times writer failover was completed and succeeded |
155-
| writerFailover.completed.failed.count | Counter | Number of times writer failover was completed and failed |
156-
| replicaFailover.triggered.count | Counter | Number of times replica failover was triggered |
157-
| replicaFailover.completed.success.count | Counter | Number of times replica failover was completed and succeeded |
158-
| replicaFailover.completed.failed.count | Counter | Number of times replica failover was completed and failed |
146+
| Metric name | Metric type | Description |
147+
|-----------------------------------------|-------------|--------------------------------------------------------------|
148+
| writerFailover.triggered.count | Counter | Number of times writer failover was triggered |
149+
| writerFailover.completed.success.count | Counter | Number of times writer failover was completed and succeeded |
150+
| writerFailover.completed.failed.count | Counter | Number of times writer failover was completed and failed |
151+
| replicaFailover.triggered.count | Counter | Number of times replica failover was triggered |
152+
| replicaFailover.completed.success.count | Counter | Number of times replica failover was completed and succeeded |
153+
| replicaFailover.completed.failed.count | Counter | Number of times replica failover was completed and failed |
159154

160155
### Stale DNS
161156

162-
| Metric name | Metric type | Description |
163-
|---|---|---|
164-
| staleDNS.stale.detected | Counter | Number of times DNS was detected stale |
157+
| Metric name | Metric type | Description |
158+
|-------------------------|-------------|----------------------------------------|
159+
| staleDNS.stale.detected | Counter | Number of times DNS was detected stale |

0 commit comments

Comments
 (0)