# 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 opentelemetry-api.jar and opentelemetry-context.jar which must be included in the Java classpath.

## 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 matchs 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 use otel.resource.attributes JVM arguement or OTEL_RESOURCE_ATTRIBUTES environment variable for global attributes.

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

## Running SparkGateway as an Application

First, download the OpenTelemetry Java agent (`opentelemetry-javaagent.jar`):
https://opentelemetry.io/docs/zero-code/java/agent/getting-started/

### Set Up Agent and Parameters with JVM Arguments
```
-javaagent:/path/to/opentelemetry-javaagent.jar \
-Dotel.service.name=sparkgateway \
-Dotel.metrics.exporter=otlp \
-Dotel.exporter.otlp.endpoint=http://localhost:4317
-Dotel.resource.attributes=instance=SparkGatewayServer1,port=443
```

You can use the "console" exporter for debugging purposes:
```
-javaagent:/path/to/opentelemetry-javaagent.jar \
-Dotel.metrics.exporter=console \
-Dotel.metric.export.interval=3000 \
-Dotel.resource.attributes=instance=SparkGatewayServer1,port=443
```
Adding Global Attributes (Resource Attributes)

Check https://opentelemetry.io/docs/languages/java/configuration/ for more details.

### Set Up Agent and Parameters with Environment Variables
```
JAVA_TOOL_OPTIONS="-javaagent:/path/to/opentelemetry-javaagent.jar"
OTEL_SERVICE_NAME=sparkgateway
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
OTEL_METRIC_EXPORTER=otlp
OTEL_RESOURCE_ATTRIBUTES=instance=SparkGatewayServer1,port=443
```


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