---
title: Scala instrumentation
source: https://docs.newrelic.com/docs/apm/agents/java-agent/frameworks/scala-installation-java
---

The New Relic Java agent is [compatible with Scala](https://docs.newrelic.com/docs/agents/java-agent/getting-started/compatibility-requirements-java-agent#other), and supports New Relic API calls, annotations, and [custom instrumentation](https://docs.newrelic.com/docs/java/custom-instrumentation-with-the-java-agent). All information below is supplemental to New Relic's [Java agent installation directions](https://docs.newrelic.com/docs/java/java-agent-manual-installation).

> #### 💡 TIP
>
> For Heroku, see [Java agent with Scala on Heroku](https://docs.newrelic.com/docs/agents/java-agent/heroku/java-agent-scala-heroku).

## Scala frameworks [#frameworks]

If your [framework](https://docs.newrelic.com/docs/agents/java-agent/getting-started/compatibility-requirements-java-agent#frameworks) is not natively supported by New Relic, or if you want to set up additional monitoring, [custom instrumentation](https://docs.newrelic.com/docs/agents/java-agent/custom-instrumentation/java-custom-instrumentation) is a great way to dig deeper into your application.

## Instrument Scala with the Scala API [#using-the-scala-api]

The New Relic Scala agent API lets you control, customize, and extend the
functionality of the APM Java agent using idiomatic Scala code. It can be used
alongside the [New Relic Java API](https://docs.newrelic.com/docs/agents/java-agent/api-guides/guide-using-java-agent-api/)
as well as allow users to

-   Create segments for synchronous and asynchronous anonymous functions
-   Create segments for synchronous and asynchronous code blocks
-   Create a transaction if one has not already been started

> #### ⚠️ IMPORTANT
>
> For best results when using the API, ensure that you have the latest Java agent
> release. The New Relic Scala API requires Java agent 7.1.0 or higher.

### Use the Scala API

To access the API class add the following information to your Scala configuration file:

**Configure using the \`project/build.scala\` file**

Add the following line (replacing `S.V` with the Scala version
and `X.Y.Z` with the
[Java agent version](https://docs.newrelic.com/docs/agents/java-agent/installation/update-java-agent#procedures)
you use) to the `appDependencies` method in your application's
`project/build.scala` file:

````scala
"com.newrelic.agent.java" % "newrelic-scala-api_S.V" % "X.Y.Z"
```

````

**Configure using the \`project/build.sbt\` file**

Add the following line (replacing `S.V` with the Scala version
and `X.Y.Z` with the[Java agent version](https://docs.newrelic.com/docs/agents/java-agent/installation/update-java-agent#procedures)
you use) to your application's `project/build.sbt` file:

````scala
libraryDependencies += "com.newrelic.agent.java" % "newrelic-scala-api_S.V" % "X.Y.Z"
```

````

Supported Scala versions are 2.10, 2.11, 2.12 and 2.13. Scala 3.0 users can use the 2.13 jar. The jar is deployed to Maven Central and it is also in the New Relic Java agent's installation zip file. You can call the API when the Java agent is not running. The underlying API methods are just stubs; the implementation is added when the Java agent is running.

### Segments

To create segment for a synchronous code block use `TraceOps.trace`. For
example:

```scala
import com.newrelic.scala.api.TraceOps.trace

trace("statement segment") {
    val i = 1
    val j = 2
    println(i + j)
}
// trace can also be used as an expression
val x: Int = trace("expression segment") {
    val i = 1
    val j = 2
    i + j
}
println(x) // 2
```

`trace` can also be used in Scala For comprehensions

```scala
import scala.concurrent.{ExecutionContext, Future}
import com.newrelic.scala.api.TraceOps.trace

// implicit execution
implicit val ec: ExecutionContext = ???

  val x: Option[Int] = for {
    one <- trace("segment one")(Option(1))
    two <- trace("segment two")(Option(one + 1))
    three <- trace("segment three")(Option(two + 1))
  } yield three

println(x) // Some(3)
```

If you want to create segment for an asynchronous code block containing a Scala
Future use `TraceOps.asyncTrace`. This will ensure the timing for the segment
includes the time taken for the Future to complete.

In the example below segment time will be no less than 5 seconds due to the
delay created in the wrapped Future.

```scala
import scala.concurrent.{ExecutionContext, Future}
import com.newrelic.scala.api.TraceOps.asyncTrace
// implicit execution
implicit val ec: ExecutionContext = ???

val x: Future[Int] = asyncTrace("segment name")(Future {
  Thread.sleep(5000)
  1
})
x.foreach(println) // prints 1 on completion of Future
```

`asyncTrace` can also be used in Scala For comprehensions

```scala
import scala.concurrent.{ExecutionContext, Future}
import com.newrelic.scala.api.TraceOps.asyncTrace
// implicit execution
implicit val ec: ExecutionContext = ???

 val x: Future[Int] = for {
    one <- asyncTrace("segment one")(Future(1))
    two <- asyncTrace("segment two")(Future(one + 1))
    three <- asyncTrace("segment three")(Future(two + 1))
  } yield three

x.foreach(println) // prints 3 on completion of Future
```

If you want to create segment for a synchronous anonymous function use
`TraceOps.traceFun`. For example:

```scala
import com.newrelic.scala.api.TraceOps.traceFun

val x: Option[Int] = Option(1)
            .map(traceFun("statement segment")(i => i + 1))
println(x) //Some(2)
```

If you want to create segment for an asynchronous function that returns a Scala
Future use `TraceOps.asyncTraceFun`. This will ensure the timing for the segment
includes the time taken for the function to complete.

In the example below segment time will be no less than 5 seconds due to the
delay created in the wrapped Future.

```scala
import scala.concurrent.{ExecutionContext, Future}
import com.newrelic.scala.api.TraceOps.asyncTraceFun
// implicit execution
implicit val ec: ExecutionContext = ???

val x: Future[Int] = Future(1)
            .flatMap(asyncTraceFun("statement segment")(i => Future(i + 1)))

x.foreach(println) // prints 2 on completion of Future
```

### Transactions

Transactions can be created using the `TraceOps.txn` method.
For example:

```scala
import com.newrelic.scala.api.TraceOps.txn
txn {
    val i = 1
    val j = 2
    println(i + j)
}
```

`txn` can be used as a statement (as above) or as an expression

```scala
import com.newrelic.scala.api.TraceOps.txn
val i: Int = txn(1 + 2) //transaction created
println(i) // 3
```

`txn` can be used with any of the `TraceOp` methods to create segments. The
example below create a transaction with 3 segments.

```scala
import scala.concurrent.{ExecutionContext, Future}
import com.newrelic.scala.api.TraceOps.{txn, asyncTrace}
// implicit execution
implicit val ec: ExecutionContext = ???

 val x: Future[Int] = txn(
     for {
        one <- asyncTrace("segment one")(Future(1))
        two <- asyncTrace("segment two")(Future(one + 1))
        three <- asyncTrace("segment three")(Future(two + 1))
    } yield three
 )

x.foreach(println) // prints 3 on completion of Future
```

### Futures

New Relic handles Scala futures when they're submitted to the executor, which might lead to a different outcome than you expect. The examples in this section clarifies how this works, so you know what to expect.

This example is calling a transaction block, which takes a future as its parameter and chains it to a second future:

```scala
def chainFutures(f: Future[Unit]) = txn {
     f.flatMap( _ => Future{ Thread.sleep(2000) })
}

val f = Future { Thread.sleep(5000) } // future is submitted here
chainFutures(f)
```

From this example, you might expect `chainFutures` to produce a transaction lasting 7 seconds. Instead, the New Relic UI shows the transaction finishing immediately.

The future `f` in the example is submitted by the `Future.apply()` method when it's constructed, before the transaction exists. Because `f` is submitted outside the transaction, any threadhops made during its execution aren't linked together. The downstream future, `Future{ Thread.sleep(2000) }`, is also untracked, because it's submitted in a callback after the transaction context is already gone.

There are a few things you can do to get your transaction to capture the timing of both futures.

-   Although you might not be able to change when `f` is submitted, you can time it using the `asyncTrace` method. This times `f` from the moment the transaction is started (but will not track threadhops made by `f`).
-   You can use a token to link the callback to the transaction in order to preserve the transaction context during threadhops.
-   You can add another `asyncTrace` to time the second future.

With this example, the New Relic UI shows a transaction lasting about 7 seconds, with two segments named “first future” and “second future”:

```scala
def chainFutures(f: Future[Unit]) = txn {
  val t = NewRelic.getAgent.getTransaction.getToken
  asyncTrace("future one" )(f)                                  //asyncTrace times the first future
    .flatMap(_ => {
      t.linkAndExpire()                                         //token links across potential threadhops
      asyncTrace("future two"){ Future { Thread.sleep(2000) } } //asyncTrace times the second future
    })
}
val f = Future { Thread.sleep(5000) } 
chainFutures(f)
```

## Instrument Scala with the Java agent API [#using-the-java-api]

Instrument Scala to use the New Relic API class or [annotations](https://docs.newrelic.com/docs/agents/java-agent/java-agent-api/java-agent-api-instrument-using-annotation).

1.  Add the following information to your Scala configuration file:

    **Configure using the project/build.scala file**

    Add the following line (replacing `X.Y.Z` with the [Java agent version](https://docs.newrelic.com/docs/agents/java-agent/installation/update-java-agent#procedures) you use) to the appDependencies method in your application's `project/build.scala` file:

    ````scala
    "com.newrelic.agent.java" % "newrelic-api" % "X.Y.Z"
    ```

    ````

    **Configure using the project/build.sbt file**

    Add the following line (replacing `X.Y.Z` with the [Java agent version](https://docs.newrelic.com/docs/agents/java-agent/installation/update-java-agent#procedures) you use) to your application's `project/build.sbt` file:

    ````scala
    libraryDependencies += "com.newrelic.agent.java" % "newrelic-api" % "X.Y.Z"
    ```

    ````
2.  Import the NewRelic class and use it in your application:

    ```java
    import com.newrelic.api.agent.NewRelic
    ...
    NewRelic.setTransactionName(null, "/myTransaction");
    ```

### More API functions [#other-api]

For more about the Java agent API and its functionality, see the [Java agent API introduction](https://docs.newrelic.com/docs/agents/java-agent/custom-instrumentation/java-agent-api).

## Instrument Scala with XML instrumentation

XML instrumentation is available for any Scala application running with the Java
agent. It allows instrumentation to be added without any changes to the code.

For more information, see [Java instrumentation by XML](https://docs.newrelic.com/docs/java/custom-instrumentation-by-xml/).

## Additional instrumentation

If you use Kamon, take a look at the New Relic [Kamon reporter](https://docs.newrelic.com/docs/integrations/open-source-telemetry-integrations/open-source-telemetry-integration-list/kamon-reporter).