Scala

Traces	Metrics	App Logs	Custom Logs	Profiling
✅	✅	✅	✅	✅

1. Prerequisites

Middleware Host Agent running on the same machine (or reachable). In containers, point apps to the agent with MW_AGENT_SERVICE: Docker 172.17.0.1, Kubernetes mw-service.mw-agent-ns.svc.cluster.local.
Scala/SBT project (Scala 2.11.6+ is fine) and JDK 8+. Check using:
```
1scala --version
2java --version
```

Host-based

Serverless

1 Download the Middleware Java agent JAR

Grab the latest release of the Middleware Java agent JAR from GitHub and place it in your project (e.g., project root or a lib/ directory).

Keep the filename versioned (e.g., middleware-javaagent-1.x.y.jar) and commit it or fetch it during CI.

2 Wire the agent in build.sbt

Enable a forked JVM and pass -javaagent + service name via javaOptions. (Forking is required for SBT to apply javaOptions to your app’s run.)

1// build.sbt
2ThisBuild / scalaVersion := "2.13.14"
3
4// ensure SBT forks for run so javaOptions apply
5(run / fork) := true
6
7(run / javaOptions) ++= Seq(
8  // point to where you stored the agent jar
9  "-javaagent:middleware-javaagent-1.6.0.jar",
10  // logical service name shown in Middleware APM
11  "-Dotel.service.name={APM-SERVICE-NAME}"
12)

(Your existing Scala page uses the same javaOptions structure; we’re just adding the fork so it takes effect.) Alternative: if you prefer, you can manage javaagents via the community sbt-javaagent plugin instead of manual javaOptions.

3 Run your app with your account key

Your Middleware API key is required; export it and run the app via SBT:

1MW_API_KEY="<API-key>" sbt run

If you’re not running a Host Agent, point the agent straight to Middleware’s ingest and keep the rest identical:

1// build.sbt (add one more property)
2(run / javaOptions) ++= Seq(
3  "-Dotel.exporter.otlp.endpoint=https://ruplp.middleware.io" // serverless ingest URL
4)

OpenTelemetry Java agents accept the standard otel.exporter.otlp.endpoint property; the SDK constructs the signal-specific paths as needed for OTLP/HTTP. You’ll still export MW_API_KEY=... alongside sbt run.

(Optional) Custom logs from your Scala code

If you want to emit custom logs (INFO/WARN/DEBUG/ERROR) that correlate with traces, add the agent-apm-java library to your build and use its Logger:

Add dependency (SBT):

1// build.sbt
2libraryDependencies += "io.github.middleware-labs" % "agent-apm-java" % "0.0.18"

Use the logger (Scala/Java interop):

1// anywhere in your app code
2import io.github.middlewarelabs.agentapmjava.Logger
3
4Logger.info("info message")
5Logger.debug("debug message")
6Logger.warn("warn message")
7Logger.error("error message")

Record stack errors Call recordError from a catch block to attach stack traces to the active span:

1try {
2  // ...
3} catch {
4  case e: Exception =>
5    io.github.middlewarelabs.agentapmjava.Logger.recordError(e)
6    throw e
7}

View your data

After you start the app, wait 3–5 minutes, then open Traces, Logs, and Profiling in Middleware to verify data is flowing. (This mirrors your Scala page’s flow.)

SBT notes & tips

Forking is required for javaOptions (like -javaagent) to apply to sbt run. Configure (run / fork) := true.
If you package with sbt-native-packager, you can also push Java options into start scripts via Universal / javaOptions or add extra defines to scripts.
When sending data without a local collector, otel.exporter.otlp.endpoint is the standard knob; OTLP exporters also support header-based auth via otel.exporter.otlp.headers if you ever need it.

Environment variables

Key/Option	Where it's used	Purpose	Example
`MW_AGENT_SERVICE`	Containerized host-based	Route app → Host Agent	`172.17.0.1` (Docker), `mw-service.mw-agent-ns.svc.cluster.local` (K8s).
`MW_API_KEY`	Runtime env	Your Middleware account key, required for export	`export MW_API_KEY="…"`; then `sbt run`.
`-Dotel.service.name`	`javaOptions`	Logical service name shown in APM	`-Dotel.service.name=payments-scala`
`-Dotel.exporter.otlp.endpoint`	`javaOptions`(serverless)	Send telemetry directly to Middleware ingest (no Host Agent)	`-Dotel.exporter.otlp.endpoint=https://ruplp.middleware.io.`

Troubleshooting

No telemetry appears → Confirm (run / fork) := true and the -javaagent: path is correct. SBT only applies javaOptions to a forked run.
Still no data on serverless → Ensure the endpoint property is set (otel.exporter.otlp.endpoint) and that your key is present. OTLP HTTP exporters derive /v1/{signal} paths automatically when you set a base endpoint.
Packaging instead of sbt run → Use sbt-native-packager’s Universal / javaOptions or script defines so the agent flags end up in the generated start scripts.

Need assistance or want to learn more about Middleware? Contact our support team at [email protected] or join our Slack channel.