Instantiate APM Tracer

Follow these steps to add tracing support to your application:

Note

For Helidon configuration, skip these steps and refer to Use APM Tracer in Helidon.
  1. Import the opentracing Tracer and APM Tracer classes by doing the following:

    import io.opentracing.Tracer;
    import com.oracle.apm.tracer.ApmTracer;
  2. APM Tracer can be instantiated in builder style. The constructor of ApmTracer.Builder has 2 parameters: tracerName and serviceName.

    • tracerName: Name of this tracer. It can be any string name except null.
    • serviceName: Name of service reported by this tracer. It can be any string except null.
    Tracer tracer = new ApmTracer.Builder(String tracerName, String serviceName)            
            .<configuration methods>            
            .build();

Before calling the build() method to create the APM Tracer instance, it can be configured with configuration methods. Some configuration methods can also be configured by setting Java system properties and environment variables.

Configuration Methods

Method Default Description Equivalent Java System Property Equivalent Environment Variable
withDataUploadEndpoint(String endpoint)   Set APM data upload endpoint required for Oracle APM cloud communication. com.oracle.apm.agent.data.upload.endpoint com_oracle_apm_agent_data_upload_endpoint
withDataUploadKey(String dataKey)   Set APM data upload key required for Oracle APM cloud communication. com.oracle.apm.agent.private.data.key com_oracle_apm_agent_private_data_key

withTag(String key, String value)

withTag(String key, Boolean value)

withTag(String key, Number value)

withTags(Map<String, Object> tags)

  Set static tags to be included in all tracing spans.    
withLogDirectory(String directory) ./apm-tracer-log Specify full path of log directoy where all APM Tracer logs are written to. If this is left unset, then the default log directory, apm-tracer-log, is created in the working directory of JVM. com.oracle.apm.agent.log.directory com_oracle_apm_agent_log_directory

withProperty(String key, String value)

withProperties(Map<String, String> properties)

 

Set one or more APM Tracer properties. This allows properties be set programmatically at APM Tracer startup time. All properties can also be set via Java system properties or environment variables.

Properties are ignored if either key or value is null.

   
withMicrosecondAccurateTimestamp(boolean microsecondAccuracy) false Set all timestamps to microseconds accuracy when this is true. The default is milliseconds accuracy.    
withCollectMetrics(boolean collectMetrics) true

Set APM Tracer to collect server metrics and report to OCI APM cloud. The default is true.

User can access all collected server metrics from OCI Telemetry.

See Collect Metrics for details of collected server metrics.

   
withCollectResources(boolean collectResources) true

Sets APM Tracer to collect server resources and report to OCI APM cloud.

All collected resources are used as dimension for data query.

See Collect Metrics for details of collected server metrics.

   
withDaemonChannel(String channel)   APM Daemon channel is a socket connection between Tracer and Daemon. Format of this property value is <host>:<port>. When Daemon is started with this property set, Daemon accept socket connection and listen data on this specified channel. When Tracer is started with this set, then the data upload endpoint is ignored, and data is only sent to Daemon using this socket channel. com.oracle.apm.agent.daemon.channel com_oracle_apm_agent_daemon_channel
build()   Instantiate APM Tracer instance.    

Other Properties

Properties can be set as Java system properties, environment variables, or by using with Property() builder method.

Java System Property Environment Variable Default Description
com.oracle.apm.agent.daemon.channel com.oracle.apm.agent.daemon.channel   APM Daemon channel is a socket connection between Tracer and Daemon. Format of this property value is <host>:<port>. When Daemon is started with this property set, Daemon accepts socket connection and listens data on this specified channel. When Tracer is started with this set, then the data upload endpoint is ignored, and data is only sent to Daemon using this socket channel.
com.oracle.apm.agent.data.upload.proxy.url com_oracle_apm_agent_data_upload_proxy_url   Proxy server URL for Oracle APM server connection. Only HTTP proxy is supported.
com.oracle.apm.agent.log.filesize.mb com_oracle_apm_agent_log_filesize_mb 20mb Log file size. You can specify the log file size using this property. The default value is "20" i.e 20MB will be the file size of one log file.
com.oracle.apm.agent.log.rotation.files.count com_oracle_apm_agent_log_rotation_files_count 2 Number of files that can be created to store logs with rolling over mechanism. Example : If we specify "2" as value of this property then the logs will be stored in the first file until we reach the limit of file size. Once the file size limit is reached, new file will be created and it will continue to store logs. After reaching the file size limit in the second file, it will delete the first file and it will start logging in the first file. Files will be named appropriately with a numeric number suffix. For example, ApmTracer.log and ApmTracer1.log. The default value is "2" i.e 2 files will be used to store logs.
com.oracle.apm.agent.logging.level com_oracle_apm_agent_logging_level INFO Log level can be SEVERE, WARNING, INFO, DEBUG in order from least to most entries written to ApmTracer.log.
com.oracle.apm.agent.tracer.propagation.type com_oracle_apm_agent_tracer_propagation_type B3

APM Tracer will add and read HTTP headers in order to connect spans across HTTP calls. There are various types of propagation header formats that can be used to accomplish this. If you are also working with other types of tracers, such as Zipkin or Jaeger then this setting may need to be adjusted so they can work together.

  • B3: Default format used by Zipkin Tracer. APM Tracer will use this one by default.

  • Header names: X-B3-TraceId, X-B3-SpanId, X-B3-ParentSpanId, X-B3-Sampled.

    Note the single header case (b3) is not currently supported.

  • Jaeger: Default format used by Jaeger Tracer. Header names: uber-trace-id

  • APM: Old format used by APM Tracer. Header names: X-ORACLE-APM-SPAN-ID, X-ORACLE-APM-TRACE-ID

  • W3C: Trace Context format from W3C. Header names: traceparent, tracestate