Scala support matrix

JREs

Oracle
1.8
Oracle, OpenJDK, IBM
1.7
Sun, OpenJDK, IBM
1.6
Sun, IBM
1.5

Java http clients

Apache HttpClient
3.x - 4.4.x
Apache CXF
2.2.1 - CXF 3.0.3
Apache Axis2
1.5 - 1.6.2
Sun Jersey
1.2 - 1.18.3
Glassfish Jersey JAX-RS 2.0
2.0-m-08 - 2.14
Glassfish JAX-WS RI
2.1 - 2.2.9
JBoss RESTEasy
2.0.0 - 3.0.10 Final
JDK javax.xml.soap
1.6 - 1.7.0_22
Restlet
2.0 - 2.3
SAAJ javax.xml.soap
1.3
Spring RestTemplate
3.0.0 - 4.1.3.RELEASE
Play WS
2.2 - 2.4
HttpURLConnection
1.5 - 1.8
Spray HTTP client
1.1 - 1.3

Java frameworks

Apache MyFaces JSF
1.2 - 2.2.8
Apache Struts
2.x
Grails
1.0 - 1.3, 1.4 - 2.3.6
JBoss EJB
4.x - 8.x
Play
1.1 - 2.4
Play2War
2.0.x - 2.3.x
Spring 3 MVC
4.1.3.RELEASE
Spring Web Flow
1.x - 2.x
Spray-can
1.1.x - 1.3.x

Java app servers

Glassfish
2.1.x, 4.1.x
JBoss
5.x - 7.x
Jetty
6.x - 9.x
JRuby
see ruby
Resin
3.x - 4.0.x
Tomcat
5.x - 8.x
WebLogic
11g - 12c
WebSphere
7.5, 8.0, 8.5

Java databases

Cassandra CQL via Datastax
1.0.0 - 2.0.x
Cloudera HBase
0.92.x - 1.1.1
MongoDB
2.5.x - 3.0.x
Oracle JDBC Thin
11.x, 12.x
Redis Jedis
1.3.0 - 2.6.1
Redis Redisson
1.0.1 - 1.3.0
IBM DB2
MySQL
Oracle JDBC OCI
PostgreSQL

More Java databases

The following can also be instrumented if the agent.jdbcInstAll flag in the java agent config is set to true.

  • Apache Derby
  • Apache DBCP
  • c3p0
  • HSQLDB
  • Microsoft SQL
  • Sybase

Other Java components

Apache Thrift
0.8, 0.9
Apache Solr
1.3.0 - 4.10.3
Ehcache
1.3.x-2.8.x
Spymemcached
2.4.x - 2.11.5
xmemcached
1.2.5 - 2.0.0
Akka-actor
2.1 - 2.4
Spray-can HTTP server
1.1.x - 1.3.x
Spray-can HTTP server
1.1.x - 1.3.x
Undertow
1.0 - 1.3
Java ThreadPoolExecutor
1.5 - 1.8
RabbitMQ
2.6.0 - 3.5.3
JMX

Installing on linux

Scala instrumentation uses the same java .jar as the java instrumentation:

  1. Install the jar and related JNI libraries in /usr/local/tracelytics.

    # redhat/centos
    sudo yum install tracelytics-java-agent tracelytics-java-agent-native
    # debian/ubuntu
    sudo apt-get install tracelytics-java-agent tracelytics-java-agent-native
    
  2. Update your application server start-up scripts to load the agent by adding a -javaagent parameter to the jvm; see the server-specific instructions. For applications run on specific build platforms, please refer to the build-platform-specific instructions.

  3. The -javaagent parameter must be provided at jvm start-up, so restart your application server.

Server-specific instructions

spray-can development mode

Spray-can is the http connector/server of the spray framework. It can be run via sbt/activator in developer mode or as a plain jar in production mode. For instructions on installing the java agent, see the sbt/activator instructions.

spray-can production mode

To add our java agent when running in production mode, simply append the jvm option -javaagent:/usr/local/tracelytics/tracelyticsagent.jar to the spray java process. For example, if it’s run on a fat jar:

java -javaagent:/usr/local/tracelytics/tracelyticsagent.jar -jar your-spray-jar.jar

Play 2.3 - 2.4 development mode

For instructions on installing the java agent, see the sbt/activator instructions.

Play 2.3 - 2.4 production mode

Running ‘activator dist’ generates a startup script, and the option to add on our java agent is pretty similar to previous versions.

Workaround required: The windows startup script needs a work around to overcome a known issue with activator related to length limitation with cmd.exe command line strings.

bin/<startup script> -J-javaagent:/usr/local/tracelytics/tracelyticsagent.jar

Play 2.0 - 2.2 development mode

Add the following line just before the java command in the play build script. Then start your play project using ‘play run’.

JAVA_OPTS="$JAVA_OPTS -javaagent:/usr/local/tracelytics/tracelyticsagent.jar"

Play 2.0 - 2.2 production mode

The ‘play start’ command does not support the javaagent option. Instead, start the play project using the script in the bin folder of /path/to/project with the javaagent argument.

# play 2.2 or later
bin/<startup script> -J-javaagent:/usr/local/tracelytics/tracelyticsagent.jar
# play 2.0 - 2.1
bin/<startup script> -javaagent:/usr/local/tracelytics/tracelyticsagent.jar

Play 1.1.1

Start the play project using the command ‘play run’ with the javaagent argument.

play run myproject -javaagent:/usr/local/tracelytics/tracelyticsagent.jar

Build-platform-specific instructions

Activator and sbt are platforms to build and start java/scala apps, usually for development, not production. Some frameworks such as play, spray use sbt/activator by default.

sbt
  • To add the java agent to all sbt projects when running in development mode, i.e., ‘sbt run’, add the following line to the end of sbt/install/directory/conf/sbtopts.
  • To add the java agent to a specific sbt project, add the following line to .sbtopts in your sbt project folder, creating that file if necessary.

     -J-javaagent:/usr/local/tracelytics/tracelyticsagent.jar
    
Activator
  • To add the java agent to all activator projects when running in development mode, i.e., ‘activator run’, add the following line to user\home\directory.activator\activatorconfig.txt.
  • To add the java agent to a specific version only, add the following line to the end of user\home\directory.activator\version\activatorconfig.txt.
  • To add the java agent to a specific activator project, add the following line to environment variable ACTIVATOR_OPTS, SBT_OPTS or JAVA_OPTS.

     -javaagent:/usr/local/tracelytics/tracelyticsagent.jar
    

Installing on windows

Scala instrumentation uses the same java .jar as the java instrumentation:

  1. We have a java agent installer that you can download. It installs the required jar and configuration files under ‘Program Files\AppNeta\TraceView\java’.
  2. You’ll need to update your application server start-up scripts to load the agent at start-up by adding a -javaagent parameter to the jvm. See the server-specific instructions. For applications run on specific build platforms, please refer to the build platform specific instructions.
  3. The -javaagent parameter must be provided at jvm start-up, so restart your application server.

Server-specific instructions

spray-can development mode

Spray-can is the http connector/server of the spray framework, like netty for play. It can be run via sbt/activator in dev mode, or run as a plain jar in production mode. For instructions on installing the java agent, see the sbt/activator instructions.

spray-can production mode

To add our java agent when running in production mode, simply append the jvm option -javaagent:/path/to/java/agent.jar to the spray java process. For example, if it’s run on a fat jar:

java -javaagent:/path/to/java/agent.jar -jar your-spray-jar.jar

Play 2.3 - 2.4 development mode

For instructions on installing the java agent, see the sbt/activator instructions

Play 2.3 - 2.4 production mode

Running ‘activator dist’ generates a startup script, and the option to add on our java agent is pretty similar to previous versions.

Workaround required: The windows startup script needs a work around to overcome a known issue for activator related to length limitation with cmd.exe command line strings.

bin/<startup script> -J-javaagent:C:\PROGRA~1\AppNeta\TraceView\java\tracelyticsagent.jar

Play 2.0 - 2.2 development mode

Add the following line just before the java command in the play build script. Then start your play project using ‘play run’.

set JAVA_OPTS=%JAVA_OPTS% -javaagent:"C:\Program Files\AppNeta\TraceView\java\tracelyticsagent.jar"

Play 2.0 - 2.2 production mode

The ‘play start’ command does not support the javaagent option. Instead, start the play project using the script in the bin folder of /path/to/project with the javaagent argument.

# play 2.2 or later
bin\<startup script> -J-javaagent:"C:\Program Files\AppNeta\TraceView\java\tracelyticsagent.jar"
# play 2.0 - 2.1
bin\<startup script> -javaagent:"C:\Program Files\AppNeta\TraceView\java\tracelyticsagent.jar"

Play 1.1.1

Start the play project using the command ‘play run’ with the javaagent argument.

play run myproject -javaagent:"C:\Program Files\AppNeta\TraceView\java\tracelyticsagent.jar"

Build-platform-specific instructions

Activator and sbt are platforms to build and start java/scala apps, usually for development, not production. Some frameworks such as play, spray use sbt/activator by default.

sbt
  • To add the java agent to all sbt projects when running in development mode, i.e., started using sbt run, add the following line to the end of sbt installation directory\conf\sbtconfig.txt.
  • To add the java agent to a specific sbt project, add the line to environment variable SBT_OPTS or JAVA_OPTS.
-javaagent:"C:\Program Files\AppNeta\TraceView\java\tracelyticsagent.jar"
Activator
  • To add the java agent to all activator projects when running in development mode, i.e., started using activator run, add the following line to the end of user-home.activator\activatorconfig.txt, creating the file if necessary.
  • To add the java agent to a specific version only, add the following line to user-home.activator_activator-version_\activatorconfig.txt.
  • To add the java agent to a specific sbt project, add the following line to environment variable CFG_OPTS, ACTIVATOR_OPTS, SBT_OPTS or JAVA_OPTS.
-javaagent:"C:\Program Files\AppNeta\TraceView\java\tracelyticsagent.jar"

Installing with maven

The agent can be installed by our maven plugin, which requires maven 3, or it can be obtained as a dependency and further processed by other other popular plugins.

Install using the AppNeta plugin

The AppNeta maven plugin provides two goals, ‘install-agent’ and ‘download-agent’. Both of the goals download a .zip archive containing the AppNeta java agent and unzip it to a configurable local location. Both can be run from within a maven project, or from the command line.

install-agent

Run install-agent when the agent is going to be installed and used on the local machine.

mvn com.appneta.agent.java:appneta-maven-plugin:install-agent
# use optional parameters if more control is required
mvn com.appneta.agent.java:appneta-maven-plugin[:1.0.0]:install-agent [-D agentVersion=x.x.x] [-D agentLocation=/path/to/agent]
agentLocation
(Optional) The desired location of the agent. Defaults to C:\Program Files\TraceView\java on Windows systems and /usr/local/tracelytics on linux. Make sure that the mvn command has write permissions for the target location.
agentVersion
(Optional) The desired agent version. Defaults to the latest version available. In case of re-installation, the plugin respects the agent config file ,javaagent.json, that is already present, and the newly installed config file, if different, is renamed to javaagent.json.new. The old file still will be used by the agent, but in such cases a merge might be needed.

download-agent

Run download-agent when the agent files are needed in the build process and are picked up by subsequent plugins and/or used in a later build stage. download-agent can be run from from a maven project. For example, you could add the following plugin to your pom.xml file:

 1 <plugin>
 2     <groupId>com.appneta.agent.java</groupId>
 3     <artifactId>appneta-maven-plugin</artifactId>
 4     <version>1.0.0</version>
 5     <executions>
 6         <execution>
 7             <phase>prepare-package</phase>
 8             <configuration>
 9                 <agentLocation>/path/to/agent</agentLocation><!--optional-->
10                 <agentOperatingSystem>linux</agentOperatingSystem><!--optional-->
11                 <agentVersion>x.x.x</agentVersion><!--optional-->
12             </configuration>
13             <goals>
14                 <goal>download-agent</goal>
15             </goals>
16         </execution>
17     </executions>
18 </plugin>
agentLocation
(Optional) The target download location. Default to the current project build directory.
agentVersion
(Optional)The desired agent version. Defaults to the latest version available.
agentOperatingSystem
(Optional) Defines the target operating system so the natives for it can be downloaded. The possible values are: ‘windows’, ‘linux’, and ‘all’; defaults to ‘all’.

Obtain the agent as a dependency

The agent can also be obtained as a dependency and be further processed using other popular maven plugins.

  1. Add the appneta-agent artifact to your maven project as a dependency. It’s a zip file containing all of the AppNeta agent related files:

    <dependency>
        <groupId>com.appneta.agent.java</groupId>
        <artifactId>appneta-agent</artifactId>
        <version>x.x.x</version>
        <type>zip</type>
    </dependency>
    
  2. Unzip the archive by using the maven dependency plugin:

    <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-dependency-plugin</artifactId>
        <version>2.6</version>
        <executions>
            <execution>
                <id>unpack-zip</id>
                <phase>prepare-package</phase>
                <goals>
                    <goal>unpack-dependencies</goal>
                </goals>
                <configuration>
                    <includeArtifactIds>appneta-agent</includeArtifactIds>
                    <outputDirectory>${project.build.directory}/agent</outputDirectory> 
                </configuration>
            </execution>
        </executions>
    </plugin>
    

After installing with maven: The maven instructions only downloads and installs the java instrumentation. You still need to update your application start-up scripts and restart the server. See installing on linux or installing on windows.

Upgrading instrumentation

centos/rhel

  1. Check for updates to our java packages.

    yum info tracelytics-java-agent tracelytics-java-agent-native
    
  2. Pending releases are listed under an ‘available packages’. If you don’t see this you’re all up to date! If you there are new versions available, upgrade by running:

    yum -y update tracelytics-java-agent tracelytics-java-agent-native
    
  3. If you installed a new version of the java agent, restart your application.

debian/ubuntu

  1. Check for updates to our java packages.

    apt-get update
    apt-cache policy tracelytics-java-agent tracelytics-java-agent-native
    
  2. If ‘latest version’ matches ‘candidate version’ you’re all up to date! If there are new versions available, upgrade by running.

    apt-get install --only-upgrade tracelytics-java-agent tracelytics-java-agent-native
    
  3. If you installed a new version of the java agent, restart your application.

Configuring instrumentation

There are two ways to configure the java agent:

  1. Use the -javaagent command line parameter as follows; the config option can be used for a file in a different location. If this and the following method are both used to set the same property, the -javaagent command takes precedence.

    -javaagent:/usr/local/tracelytics/tracelyticsagent.jar=config=/path/to/file
    
  2. Use the javaagent.json configuration file. By default the config is in the same folder as the tracelyticsagent.jar, usually /usr/local/tracelytics/javaagent.json.

Common configuration tasks:

JMX metrics

JMX can be used to gather diagnostic and performance-related by exporting MBeans from the JVMs running your application. Our agent will automatically import key health metrics from any instrumented JVM. It’s also possible to collect and visualize additional MBean data. JMX data is visible in two places in TraceView: organized by host on the hosts page, and visible on a per-app basis for easy comparison on the app dashboard pages.

monitor.jmx.scopes is a json configuration file where you can add the MBeans and attributes you want TraceView to collect. Each entry in this file refers to a ‘scope’ consisting of an object name and attribute list in the form: “<Object Name>”:[“<Attribute 1>”, “<Attribute 2>“…]

"java.lang:type=Memory":["HeapMemoryUsage", "NonHeapMemoryUsage"]
Object name

Refers to the pattern for JMX MBean look-up. A single object name can match multiple Mbeans. The following example matchs all MBeans exposed by domain ‘Catalina’ with type ‘Manager’.

"Catalina:type=Manager,*"
Attribute

the object name. If all attributes under an MBean are to be collected, use a wild card string. The following example collects all attributes of the MBean matching the object name ‘java.lang.type=Memory’.

"java.lang:type=Memory":"*"

Complete list of config options

The following is the complete list of instrumentation configuration options:


    agent.hideParams

    key
    agent.hideParams
    description
    By default url query args are reported for both incoming urls and outgoing calls to remote services. Set agent.hideParams and instrumentation will stop collecting and reporting query args from incoming urls.
    required?
    No
    possible values
    Value is an array of module names. Valid module names are:
    ALL
    hide url query args for all instrumented modules
    SERVLET
    http servlets/filters
    NETTY
    netty server
    APACHE_HTTP
    apache http client
    WEB_SERVICE
    soap/rest clients
    JBOSS
    jboss ejb client/server
    URL_CONNECTION
    HttpURLConnection client
    AKKA_ACTOR
    Akka actor Messages
    SPRAY_CLIENT
    Spray client
    UNDERTOW
    Undertow server
    default
    Disabled. Do not hide query parameters.
    history
    Added akka, spray, and undertow in version 5.0.1.
    example
    "agent.hideParams":["SERVLET", "APACHE_HTTP"]

    agent.logging

    key
    agent.logging
    description
    Set the logging level.
    required?
    Yes
    possible values
    Valid log levels in order of descending severity are ‘fatal’, ‘warn’, ‘info’, ‘debug’, and ‘trace’, and ‘off’.
    default
    info
    cli
    javaagent: logging
    history
    -
    example
    "agent.logging":"info"

    java agent config

    key
    None
    description
    Specify the location location of the config file.
    required?
    Yes
    default
    /usr/local/tracelytics/javaagent.json
    cli
    javaagent: config
    history
    -
    example
    javaagent:/usr/local/tracelytics/tracelyticsagent.jar=config=<config file custom location>

    agent.tracingMode

    key
    agent.tracingMode
    description
    Change the tracing mode.
    required?
    Yes
    possible values
    always
    (Default) Continue existing traces, otherwise attempt to start a new one.
    through
    Continue existing traces, but never start them. This mode assumes that a higher layer makes the decision about whether to trace.
    never
    Never continue existing traces or start new ones.
    cli
    javaagent: tracing_mode
    history
    -
    example
    "agent.tracingMode":"through"

    agent.traceAjax

    key
    agent.traceAjax
    Description
    Enable rum ajax instrumentation. When set to ‘true’, ajax calls on the browser side are traced.
    required?
    Yes
    default
    false
    cli
    javaagent: trace_ajax
    history
    -
    example
    "agent.traceAjax":true

    java agent access key

    key
    None
    description
    Override the access key defined in /etc/tracelytics.conf. required?
    No
    cli
    javaagent: access_key
    history
    -
    example
    javaagent:/usr/local/tracelytics/tracelyticsagent.jar=access_key=<access key>

    agent.layer

    key
    agent.layer
    description
    Override the default layer name, which is the application server, e.g., tomcat, jetty, jboss, etc, detected at start up. required?
    No
    cli
    javaagent: layer
    history
    -
    example
    "agent.layer":"MyLayer" (json) or javaagent:/usr/local/tracelytics/tracelyticsagent.jar=layer=MyLayer (jvm args)

    agent.jdbcInstAll

    key
    agent.jdbcInstAll
    description
    If ‘false’ the agent will instrument on sql elements of only the most popular packages, e.g., mysql, postgres, oracle, DB2. If ‘true’ it will instrument sql elements on all packages that extend java.sql classes.
    required?
    Yes
    default
    false
    cli
    javaagent: jdbc_inst_all
    history
    -
    example
    "agent.jdbcInstAll":true (json) or javaagent:/usr/local/tracelytics/tracelyticsagent.jar=jdbc_inst_all=true (jvm args)
    Notes
    Setting this parameter to ‘true’, could introduce noise into your trace data.

    agent.jdbcInstParams

    key
    agent.jdbcInstParams

    Record the actual parameters used for jdbc prepared statements.

    required?
    No
    default
    true
    history
    -
    example
    "agent.jdbcInstParams":true

    agent.jdbcSanitize

    key
    agent.jdbcSanitize
    required?
    No
    possible values
    0
    disable sanitizing
    1
    remove literals auto-detecting literal quotes
    2
    remove literals dropping doubled quoted values
    4
    remove literals keeping double quoted values
    default
    0
    history
    -
    example
    "agent.jdbcSanitize":1

    agent.extendedBackTraces

    key
    agent.extendedBackTraces
    description
    Attempt to capture an extended set of back traces.
    required?
    No
    default
    false
    history
    -
    example
    "agent.extendedBackTraces":true
    Notes
    This might slow down performance in certain setups.
    related configs
    agent.extendedBackTracesByModule

    agent.extendedBackTracesByModule

    key
    agent.extendedBackTracesByModule
    description
    There is an extended set of backtraces that is disabled by default due to performance concerns. That extended set of backtraces can be enabled selectively by this parameter. To enable the whole extended set of backtraces, use agent.extendedBackTraces instead.
    required?
    No
    default
    Not present. Extended backtraces disabled.
    Possible values
    An array of module names. Valid module names are:
    X_MEMCACHED
    Caching operations on xmemcahed
    PLAY
    Play template rendering
    SLING
    Sling request processing
    RABBIT_MQ
    RabbitMQ client operations
    example
    agent.extendedBackTracesByModule":["PLAY","SLING"]
    related configs
    agent.extendedBackTraces

    agent.hostnameOverride

    key
    agent.hostnameOverride
    description
    Override the reported hostname with another value required?
    No
    cli
    javaagent: hostname_override
    history
    -
    example
    "agent.hostnameOverride":"my-host-name" (json) or javaagent:/usr/local/tracelytics/tracelyticsagent.jar=hostname_override=my-host-name (jvm args)

    monitor.processName

    key
    monitor.processName
    description
    Identify server/JVM providing metrics. Modify this parameter if there are multiple servers/JVMs running. Otherwise it is set to JVM, e.g., Tomcat JVM.
    required?
    No
    cli
    javaagent: process_name
    history
    -
    example
    "monitor.processName":"MyProcess" (json) or javaagent:/usr/local/tracelytics/tracelyticsagent.jar=process_name=MyProcess (jvm args)

    monitor.jmx.enable

    key
    monitor.jmx.enable
    description
    Enable JMX metric collection.
    required?
    Yes
    Default
    true
    history
    -
    example
    "monitor.jmx.enable":true

    monitor.jmx.interval

    key
    monitor.jmx.interval
    description
    Specify the polling interval for JMX metric collection.
    required?
    Yes
    possible values
    30000 - 300000 milliseconds
    Default
    300000
    history
    -
    example
    "monitor.jmx.interval":30000

    monitor.jmx.scopes

    key
    monitor.jmx.scopes
    description
    Specify the MBeans and attributes you want TraceView to collect.
    required?
    Yes
    history
    -
    example
    # default config
    { 
    "java.lang:type=MemoryPool,":["Usage"],
    "java.lang:type=Memory":["HeapMemoryUsage", 
       "NonHeapMemoryUsage"],                
    "java.lang:type=GarbageCollector,":["CollectionTime"],
    "java.lang:type=Threading":["ThreadCount"],
    "java.lang:type=OperatingSystem":["ProcessCpuTime", 
       "AvailableProcessors", 
       "ProcessCpuLoad"],
    "java.lang:type=Runtime,*":["Uptime"]
    }
    

    agent.hbaseScannerNext

    key
    agent.hbaseScannerNext
    description
    Instrument Hbase ‘scanner_next’. When the agent.hbaseScannerNext flag is not present or set to ‘false’, Hbase ‘scanner_next. operations will not be traced.
    required?
    No
    default
    Not present
    history
    -
    example
    "agent.hbaseScannerNext":false

    agent.akkaActors

    key
    agent.akkaActors
    description
    A list of akka actor path names to be instrumented. You may use complete names or a regular expression in java pattern format. The list also applies to the path names of routers; if a router path name matches, all of its child actors will be monitored. required?
    required
    No
    default
    Not present; no akka actor interactions reported.
    history
    Introduced in version 5.0.1
    example

    In this example, the actor with suffix path ‘my-app/user/master’, any actors with the path prefix ‘my-app/user/worker-‘, and any child actors spawned by the router with suffix path name ‘my-app/user/router’ will be instrumented.

    "agent.akkaActors":[".*/my-app/user/master", ".*/my-app/user/worker-.*", ".*/my-app/user/router"]
    Notes
    We recommend against using wildcards with generic scope, such as “.*”, which matches all actors. There could be a large number of system actors running in the background, and capturing interactions on all of them might impose noticeable overhead.

    agent.urlSampleRates

    key
    agent.urlSampleRates
    description
    Map specific sample rate or trace mode to a url matching the specified pattern. The sample rate can be used to increase/decrease the number of matching http requests that are traced. Or, completely disable traces for certain url patterns, by setting the trace mode to ‘never’. This config option should only be used by customers with legacy per-trace subscriptions. All other subscriptions have been upgraded to smart tracing.
    required?
    No
    default
    Not present
    history
    -
    cli
    javaagent: sampling_rate or javaagent: sample_rate
    example
    "agent.urlSampleRates": 
    [
        {
            ".*\\.(png|jpg|jpeg|gif)" : 
            {
                "tracingMode" : "never"
            }
        },
        {
            "www\\.importantdomain\\.com.*" :
            {
                "sampleRate" : 1000000
            }
        }
    ],
    
    Notes

    The entries are listed in the JSON array which is assigned to agent.urlSampleRates. Take note that the matching is done by the ordering of the entries, in which the first one has the highest precedence.

    TraceView retrieves the url—minus the protocol—from every http request, and then matches it against the patterns defined in the config using java regular expression. That url match is case insensitive, but it must match the regular expression completely in order to use the corresponding sample rate. Since the pattern is defined in json, double backslashes are needed for java regex escapes, one for json and the another one for the java regex. Here are examples of the most common patterns:

    • _.*\.(png|jpg|jpeg|gif|bmp)_ matches urls with extension suffixes such as .png, .jpg…
    • _www\.importantdomain\.com.*_ matches urls with prefixes of ‘www.importantdomain.com’.
    • _.*(\?|\&)redirect=true.*_ matches urls with request parameter ‘edirect’ of value ‘true’.

    Customizing instrumentation

    Customization involves adding hooks from our public API to your code so that you can to take advantage of additional filtering capabilities on the dashboard, change how requests are traced, or capture additional information during the trace. The API is based around event generation and reporting: events are created, populated with name/value pairs, and then reported to the Tracelyzer.

    You’ll need tracelytics-api.jar which is in the TraceView agent installation directory, which is by default /usr/local/tracelytics, or you can download it from http://files.tv.solarwinds.com/java/. Copy it into your build project, and use it during the development and building phases. Import or reference classes/interfaces from the com.tracelytics.api.ext package only, and ensure the API jar file/classes is accessible in your runtime classpath/environment. The java agent jar file should only be used via the javaagent jvm argument and not be included elsewhere in your runtime classpath/environment, else you might encounter classloader errors.

    The API jar file is also available for the maven users via adding the following dependency in their maven projects.

    <dependency>
        <groupId>com.tracelytics.agent.java</groupId>
        <artifactId>tracelytics-api</artifactId>
        <version>x.x.x</version>
    </dependency>
    

    When working with sbt or activator, there are two ways to include the jar as dependency: as an unmanaged dependency, or install the jar in a local maven repository and reference it in the build script as managed dependency.

    This section contains the following sub-sections:

      Scala partitions

      With hundreds of traces flowing into your dashboard, you need a way to keep them organized. For this, TraceView provides ‘partitions’, a programmatic way of classifying traces. For example, you can place traces into the following classes: anonymous, authenticated, and administrator. On the dashboard, partitions appear as a filter on the same level as urls and controller/action pairs, so in this example you could choose to limit the display to just requests of authenticated users. Traces are not assigned to any partition by default, and you are free to partition requests however you need to feel that your app is logically arranged. To assign a trace to a partition, just fire an info event anywhere within the trace and attach the partition key/value pair. Partition names may have a maximum length of 40 characters, anything longer is truncated to 40. They’re also limited to alphanumeric characters, or underscores. Any characters that don’t fit this criteria are silently converted to underscores.

      val event = Trace.createInfoEvent("some_other_layer")
      event.addInfo("something", "interesting")
      event.report()
      

      Scala custom layers

      Instrumentation creates some layers by default, e.g., ‘play’, ‘spray’, ‘akka-actor’, which more or less map to the components you’ll find in the support matrix. If these layers don’t provide enough visibility, you can further divide your code into sub-layers. How you segment your application into layers is entirely up to you. For example the out-of-box instrumentation might not recognize calls to external processes; or, maybe there’s a subsection of your code that’s worth calling out on it’s own. In any case, instrumentation offers two facilities for creating layers: one is an annotation, for use when you want to represent a particular method as a layer; this other is set of API methods that’s better used when the block of code isn’t neatly contained.

      Custom layers using annotations

      To create a custom layer using annotations:

      1. Import the com.tracelytics.api.ext.LogMethod annotation at the top of your .java class file.

        import com.tracelytics.api.ext.LogMethod
        
      2. Adding the following line above the method of interest.

        @LogMethod(layer="myLayerName", backTrace=true, storeReturn=true, reportExceptions=false)
        
      3. LogMethod also takes additional, optional key/value pairs.

        backTrace
        Reports a stack trace at the start of the method. Default: false. storeReturn
        Reports a string representation of the return value. Default: false. reportExceptions
        Reports exceptions that may be thrown by this method. Default: true.

      Manually creating layers

      To manually create a layer, you’ll need to fire an entry event before your section of code, and fire an exit event after it.

      // example 1
        def myLogicallySeparateTask() {
          val entryEvent = Trace.createEntryEvent("serviceX")
          //entryEvent.addInfo() to add extra KVs
          entryEvent.report()
             
          // do stuff
          val exitEvent = Trace.createExitEvent("serviceX");
          //exitEvent.addInfo() to add extra KVs
          exitEvent.report()
        }
      
        // example 2
        def alotOfLogicallySeparateTaks(choice : Int) {
          val reportExtraInfo = false
          choice match {
            case 0 =>
              Trace.createEntryEvent("LayerA").report()
              //doWorkA(...)
            case 1 =>
              Trace.createEntryEvent("LayerB").report()
              //doWorkB(...)
          }
              
          if (reportExtraInfo) {
            val infoEvent = Trace.createInfoEvent(null)
            //infoEvent.addInfo() to add extra info
            infoEvent.report()
          }
          
          Trace.createExitEvent(null).report() //Both these logs inherit their Layer
        }
      

      Scala function profiling

      For most situations where you want to analyze a specific region of code, it will be easiest and more informative to use our function profiling interface. The alternative is custom layers, which should generally be reserved for calls to external services that our instrumentation would not normally recognize as needing their own layer. A function profile enables you to drill down on the performance of a specific region of code within the language layer of your app, seeing how often they are hit, in what calls and traces, and how long they take.

      1. Import the com.tracelytics.api.ext.ProfileMethod annotation at the top of your .java class file.

        import com.tracelytics.api.ext.ProfileMethod
        
      2. Add the following line above the method of interest.

        @ProfileMethod(profileName="yourProfileName", backTrace=true, storeReturn=true)
        
      3. ProfileMethod also takes additional, optional key/value pairs.

        backTrace
        Reports a stack trace at the start of the method. Default: false. storeReturn
        Reports a string representation of the return value. Default: false.

      Scala controller filter

      Instrumentation supports these frameworks. If we don’t support your framework, add controller/action information by reporting an info event with the ‘controller’ and ‘action’ keys. Even if your framework doesn’t have a conventional notion of controllers and actions, you can still take advantage of this filtering capability by simply attaching whatever values that make sense to you.

      import com.tracelytics.api.ext._
      
      class YourClass {
        def yourMethod() {
          // Add the following code to your method
          // A null layer name inherits the current layer.
          val event = Trace.createInfoEvent(null)   
          event.addInfo("Controller", "your_controller",
                        "Action",  "do_something") 
          event.report(); 
        }
      }
      

      Tracing multi-threaded applications

      While instrumenting your code, you may want to report events from background/child threads and associate them with the parent thread that spawned them—assuming that a trace was already started in the parent thread. To do this, mark the entry event associated with the background thread as ‘async’ by calling .setAsync() . Then call Trace.endTrace() when that thread is done processing.

      Scala instrumentation autmatically traces and flags asynchronous operations on multi-threaded applications triggered by Scala’s Future, Akka actors, and Java ThreadPoolExecutor. Therefore only in edge cases will you need to flag them manually, for example when using a custom threadpool.

      val event = Trace.createEntryEvent(layerName)
      event.setAsync()
      event.report()
      // Your processing ...
      Trace.endTrace()
      

      Tracing across external layers

      While instrumenting your code you might want to trace a request across processes or hosts. This can be done by passing the X-Trace ID between them.

      1. The client should call Trace.getCurrentXTraceID(), which returns either a string representing the current trace or an empty string if no trace is active.
      2. The client should then send the value to the remote process by any desired means, but probably via the X-Trace HTTP header.
      3. The remote process should read the identifier and input it to Trace.continueTrace().
      4. When the remote process is done, it should end the trace using Trace.endTrace().
      5. The remote process should send the trace id back to the client by any means, but probably via the X-Trace HTTP header.
      6. The client should then associate the trace id with the next exit event that it reports by using .AddEdge(), which links the client-side and remote-side events.

      Collecting additional trace details

      Any additional information you collect will be presented on the trace details page.

        Add info events

        There are two reasons you might want to create an info event: the first is to simply to attach any meta data that may be of interest to you during later analysis of a trace. The other reason is to take full advantage of TraceView filtering capability. In short, you can classify extents by attaching a pre-defined set of specified key/value pairs. Then from the dashboard, you can filter for traces with that extent type. See special interpretation, for more on this. To add info to an extent, create an info event anywhere within the extent, call .addInfo on TraceEvent, and then report the event. You can fire multiple info events within the extent if necessary. The information events are displayed on the raw span data tab on the trace details page. If all of the key/value pairs for special interpretation are present, the extent type is reflected in the span details tab.

        val event = Trace.createInfoEvent("some_other_layer")
        event.addInfo("something", "interesting")
        event.report()
        

        Report errors and exceptions

        To report an error or exception, which actually may be any java throwable, you should call the .logException() method with the throwable as the first parameter. Typically this would be done in the catch block of a try/catch. This will generate an error event and report it to TraceView.

        tryOperation() match {
               case Success(result) => //...
               case Failure(exception) => Trace.logException(exception)
             }
        

        Report backtraces

        To report a backtrace of the current thread, create an info event, call the .addBackTrace() method of TraceEvent, and then report the event.

        val event = Trace.createInfoEvent("some_other_layer")
        event.addBackTrace()
        event.report()
        

        Scala API reference

        Further information is available at java docs.

        Real user monitoring for Scala

        Do you have an instrumented webserver? These instructions involve enabling RUM via your page template files. If apache or nginx sits in front of your app, you don’t need to enable RUM here. It’s already provided at the web server level via our auto-rum support.

        TraceView provides optional javascript-based client-side performance data via real user monitoring (RUM). In order to gather real user timing data from the browser, you’ll need to insert two scripts into your page templates via helper methods that automatically generate the required javascript. You can call these methods in any java-based template system, e.g., freemarker, velocity, etc.

        1. You’ll need to reference tracelytics-api.jar so that RUM classes can be located. Copy it into your build project and make sure it’s accessible in your runtime classpath. The jar is in the TraceView agent installation directory, which is /usr/local/tracelytics by default. Or you can download it from here.
        2. Import or or reference with fully-qualified name the java helper class that will inject the javascript. Make sure you import or reference its classes/interfaces from com.tracelytics.api.ext only.
        3. Insert the results of RUM.getHeader() just after any <meta> tags in your <head> block. It should be the first non-meta tag inside <head>.
        4. Insert the results RUM.getFooter() immediately before the closing </body> tag.
        5. When deploying your application, start the jvm with the -javaagent=tracelyticsagent.jar command line argument.
        Embedding RUM js in play templates
         1 ...
         2 @import com.tracelytics.api.ext.RUM
         3 
         4 <!DOCTYPE html>
         5 
         6 <html&gt;
         7     <head&gt;
         8         <meta ... >
         9     <!-- RUM methods return strings so you need to expose their output as shown -->        
        10     @Html(RUM.getHeader())
        11     ...
        12     </head&gt;
        13     <body&gt;
        14         ...
        15         <!-- RUM methods return strings so you need to expose their output as shown -->
        16         @Html(RUM.getFooter())
        17     </body&gt;
        18 </html>