Instantiate APM Tracer
Follow these steps to add tracing support to your application:
-
Import the opentracing Tracer and APM Tracer classes by doing the following:
import io.opentracing.Tracer; import com.oracle.apm.tracer.ApmTracer; -
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.
|