# Java and JVM telemetry with Telemio

For Java and JVM services, prefer the standard OpenTelemetry Java ecosystem and export OTLP to Telemio. The OpenTelemetry Java agent is usually the fastest starting point because it can instrument common server, HTTP client, database, messaging, and framework boundaries without changing application code.

## Recommended order

1. Check whether the service already has OpenTelemetry.
2. Prefer the OpenTelemetry Java agent or the project's existing Spring/OpenTelemetry setup for automatic instrumentation.
3. Set stable `service.name`, environment, and release/version identity.
4. Configure OTLP export through deployment configuration or environment variables.
5. Add manual OpenTelemetry spans only around business operations that automatic instrumentation cannot name clearly.
6. Correlate logs with trace context where the logging stack supports it.
7. Keep database statements and user attributes privacy-safe; do not enable sensitive capture just because the agent can expose it.

## Typical deployment shape

```text
JVM service
  -> OpenTelemetry Java agent / SDK
    -> OTLP collector or Telemio OTLP endpoint
      -> Telemio
```

Keep authentication in the server deployment's secret configuration. Unlike a native mobile binary, a JVM service running in trusted infrastructure can use server-side credentials.

## Manual spans

Manual spans are useful for operations such as:

- `order.fulfill`
- `invoice.generate`
- `search.index`
- `agent.resolve_ticket`
- a durable workflow step that has business meaning

Do not wrap every Java method in a span. Automatic instrumentation already covers many library boundaries, and excessive custom spans make traces noisy and expensive.

## JVM runtime context

When available, retain JVM runtime/process metrics beside application traces. Runtime metrics are useful for separating application latency from garbage collection, memory pressure, thread contention, or other process-level problems.

## Agentic Java workloads

If a JVM process hosts an agent or model orchestration layer, keep the ordinary service instrumentation in place and add the current OpenTelemetry GenAI/tool semantics around model calls, tools, handoffs, retrieval, and orchestration operations. The agent run should remain part of the same service trace rather than becoming an isolated telemetry stream.