# OpenTelemetry Integration

SparkGateway implements the OpenTelemetry Metrics API only, so you can use it as a library or an application. You need the `opentelemetry-javaagent.jar` (Java Agent) to use it as a standalone application.

- This feature is disabled by default. Set `otel.enabled = true` in `gateway.conf` to enable this feature. 
- SparkGateway.jar doesn't pack any opentelemetry libraries. You have to include the necessary jar files in the Java classpath: opentelemetry-api, opentelemetry-context, opentelemetry-common, opentelemetry-sdk, opentelemetry-sdk-common, opentelemetry-sdk-extension-autoconfigure,opentelemetry-sdk-extension-autoconfigure-spi, opentelemetry-sdk-metrics, opentelemetry-exporter-xxx, opentelemetry-sdk-logs (optional), opentelemetry-sdk-trace (optional)

## Metric Name Convention
- Starts with `sparkgateway_`
- Example: `sparkgateway_sessions_total`
- Attribute "session" will be attached for specific session. The value is the 9 digit session id which matches the session id in the gateway log.

## Examples of OpenTelemetry Counters
```
sparkgateway_sessions_total = 1
sparkgateway_sessions_active = 1
sparkgateway_sessions_success = 1
sparkgateway_sessions_failure = 1
sparkgateway_sessions_joined_success = 1
sparkgateway_sessions_joined_failure = 1
sparkgateway_session_byte_out = 1820 {session=274961982}
sparkgateway_session_byte_in = 223 {session=274961982}
```
Note: Please OTEL_RESOURCE_ATTRIBUTES environment variable for global attributes.

## Example of OpenTelemetry Gauge
```
sparkgateway_sessions_used = 1
```


### Set Up OpenTelemetry with Environment Variables

SparkGateway uses OpenTelemetry Java SDK and its autoconfiguration to create the OpenTelemetry instance. You can set up environment variables to manage the providers.

```
OTEL_SERVICE_NAME=sparkgateway
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
OTEL_METRIC_EXPORTER=otlp
OTEL_RESOURCE_ATTRIBUTES=instance=SparkGatewayServer1,port=443
OTEL_LOGS_EXPORTER=none
OTEL_TRACES_EXPORTER=none
OTEL_PROPAGATORS=none
```
Please check https://opentelemetry.io/docs/languages/java/configuration/#zero-code-sdk-autoconfigure for more details.

Note: For environment variables, convert the property name to uppercase and replace all `.` and `-` characters with `_`.

SparkGateway Plugin

The plugin can implement com.toremote.otel.OpenTelemetryFactory to provide your customized OpenTelemetry instance.