Deploy this integration to enable automatic instrumentation of your Java application using OpenTelemetry.

Architecture overview

This integration includes:

  • Downloading the OpenTelemetry Java agent to your application host
  • Installing the OpenTelemetry collector with Logz.io exporter
  • Establishing communication between the agent and collector

On deployment, the Java agent automatically captures spans from your application and forwards them to the collector, which exports the data to your Logz.io account.

Setup auto-instrumentation for your locally hosted Java application and send traces to Logz.io

Before you begin, you’ll need:

  • A Java application without instrumentation
  • An active account with Logz.io
  • Port 4317 available on your host system
  • A name defined for your tracing service
Download Java agent

Download the latest version of the OpenTelemetry Java agent to the host of your Java application.

Download and configure OpenTelemetry collector

Create a dedicated directory on the host of your Java application and download the OpenTelemetry collector that is relevant to the operating system of your host.

After downloading the collector, create a configuration file config.yaml with the following parameters:

receivers:
  jaeger:
    protocols:
      thrift_compact:
        endpoint: "0.0.0.0:6831"
      thrift_binary:
        endpoint: "0.0.0.0:6832"
      grpc:
        endpoint: "0.0.0.0:14250"
      thrift_http:
        endpoint: "0.0.0.0:14268"
  opencensus:
    endpoint: "0.0.0.0:55678"
  otlp:
    protocols:
      grpc:
        endpoint: "0.0.0.0:4317"
      http:
        endpoint: "0.0.0.0:4318"
  zipkin:
    endpoint: "0.0.0.0:9411"


exporters:
  logzio:
    account_token: "<<TRACING-SHIPPING-TOKEN>>"
    #region: "<<LOGZIO_ACCOUNT_REGION_CODE>>" - (Optional): Your logz.io account region code. Defaults to "us". Required only if your logz.io region is different than US East. https://docs.logz.io/user-guide/accounts/account-region.html#available-regions

  logging:

processors:
  batch:

extensions:
  pprof:
    endpoint: :1777
  zpages:
    endpoint: :55679
  health_check:

service:
  extensions: [health_check, pprof, zpages]
  pipelines:
    traces:
      receivers: [opencensus, jaeger, zipkin, otlp]
      processors: [batch]
      exporters: [logging, logzio]

Replace <<TRACING-SHIPPING-TOKEN>> with the token of the account you want to ship to.

If your account is hosted in any region other than us, replace <LOGZIO_ACCOUNT_REGION_CODE> with the applicable region code.

If your account is hosted in us, remove region: line from the config.

Start the collector

Run the following command:

<path/to>/otelcontribcol_<VERSION-NAME> --config ./config.yaml
  • Replace <path/to> with the path to the directory where you downloaded the collector.
  • Replace <VERSION-NAME> with the version name of the collector applicable to your system, e.g. otelcontribcol_darwin_amd64.
Attach the agent to the collector and run it

Run the following command from the directory of your Java application:

java -javaagent:<path/to>/opentelemetry-javaagent-all.jar \
     -Dotel.traces.exporter=otlp \
     -Dotel.metrics.exporter=none \
     -Dotel.resource.attributes=service.name=<YOUR-SERVICE-NAME> \
     -Dotel.exporter.otlp.endpoint=http://localhost:4317 \
     -jar target/*.jar
  • Replace <path/to> with the path to the directory where you downloaded the agent.
  • Replace <YOUR-SERVICE-NAME> with the name of your tracing service defined earlier.
Check Logz.io for your traces

Give your traces some time to get from your system to ours, and then open Tracing.

Controlling the number of spans

To limit the number of outgoing spans, you can use the sampling option in the Java agent.

The sampler configures whether spans will be recorded for any call to SpanBuilder.startSpan.

System property Environment variable Description
otel.traces.sampler OTEL_TRACES_SAMPLER The sampler to use for tracing. Defaults to parentbased_always_on
otel.traces.sampler.arg OTEL_TRACES_SAMPLER_ARG An argument to the configured tracer if supported, for example a ratio.

Supported values for otel.traces.sampler are

  • “always_on”: AlwaysOnSampler
  • “always_off”: AlwaysOffSampler
  • “traceidratio”: TraceIdRatioBased. otel.traces.sampler.arg sets the ratio.
  • “parentbased_always_on”: ParentBased(root=AlwaysOnSampler)
  • “parentbased_always_off”: ParentBased(root=AlwaysOffSampler)
  • “parentbased_traceidratio”: ParentBased(root=TraceIdRatioBased). otel.traces.sampler.arg sets the ratio.

Setup auto-instrumentation for your Java application using Docker and send traces to Logz.io

This integration enables you to auto-instrument your Java application and run a containerized OpenTelemetry collector to send your traces to Logz.io. If your application also runs in a Docker container, make sure that both the application and collector containers are on the same network.

Before you begin, you’ll need:

  • A Java application without instrumentation
  • An active account with Logz.io
  • Port 4317 available on your host system
  • A name defined for your tracing service
Download Java agent

Download the latest version of the OpenTelemetry Java agent to the host of your Java application.

Pull the Docker image for the OpenTelemetry collector
docker pull logzio/otel-collector-traces

This integration only works with an otel-contrib image. The logzio/otel-collector-traces image is based on otel-contrib.

Run the container

When running on a Linux host, use the --network host flag to publish the collector ports:

docker run \
-e LOGZIO_REGION=<<LOGZIO_ACCOUNT_REGION_CODE>> \
-e LOGZIO_TRACES_TOKEN=<<TRACING-SHIPPING-TOKEN>> \
--network host \
logzio/otel-collector-traces

When running on MacOS or Windows hosts, publish the ports using the -p flag:

docker run \
-e LOGZIO_REGION=<<LOGZIO_ACCOUNT_REGION_CODE>> \
-e LOGZIO_TRACES_TOKEN=<<TRACING-SHIPPING-TOKEN>> \
-p 55678-55680:55678-55680 \
-p 1777:1777 \
-p 9411:9411 \
-p 9943:9943 \
-p 6831:6831 \
-p 6832:6832 \
-p 14250:14250 \
-p 14268:14268 \
-p 4317:4317 \
-p 55681:55681 \
logzio/otel-collector-traces

Replace <<TRACING-SHIPPING-TOKEN>> with the token of the account you want to ship to.

If your account is hosted in any region other than us, replace <LOGZIO_ACCOUNT_REGION_CODE> with the applicable region code.

If your account is hosted in us, remove region: line from the config.

Attach the agent to the collector and run it

Run the following command from the directory of your Java application:

java -javaagent:<path/to>/opentelemetry-javaagent-all.jar \
     -Dotel.traces.exporter=otlp \
     -Dotel.metrics.exporter=none \
     -Dotel.resource.attributes=service.name=<YOUR-SERVICE-NAME> \
     -Dotel.exporter.otlp.endpoint=http://localhost:4317 \
     -jar target/*.jar
  • Replace <path/to> with the path to the directory where you downloaded the agent.
  • Replace <YOUR-SERVICE-NAME> with the name of your tracing service defined earlier.
Check Logz.io for your traces

Give your traces some time to get from your system to ours, and then open Tracing.

Controlling the number of spans

To limit the number of outgoing spans, you can use the sampling option in the Java agent.

The sampler configures whether spans will be recorded for any call to SpanBuilder.startSpan.

System property Environment variable Description
otel.traces.sampler OTEL_TRACES_SAMPLER The sampler to use for tracing. Defaults to parentbased_always_on
otel.traces.sampler.arg OTEL_TRACES_SAMPLER_ARG An argument to the configured tracer if supported, for example a ratio.

Supported values for otel.traces.sampler are

  • “always_on”: AlwaysOnSampler
  • “always_off”: AlwaysOffSampler
  • “traceidratio”: TraceIdRatioBased. otel.traces.sampler.arg sets the ratio.
  • “parentbased_always_on”: ParentBased(root=AlwaysOnSampler)
  • “parentbased_always_off”: ParentBased(root=AlwaysOffSampler)
  • “parentbased_traceidratio”: ParentBased(root=TraceIdRatioBased). otel.traces.sampler.arg sets the ratio.

Overview

You can use a Helm chart to ship Traces to Logz.io via the OpenTelemetry collector. The Helm tool is used to manage packages of pre-configured Kubernetes resources that use charts.

logzio-otel-traces allows you to ship traces from your Kubernetes cluster to Logz.io with the OpenTelemetry collector.

This chart is a fork of the opentelemtry-collector Helm chart. The main repository for Logz.io helm charts are logzio-helm.

Standard configuration

Deploy the Helm chart

Add logzio-helm repo as follows:

helm repo add logzio-helm https://logzio.github.io/logzio-helm
helm repo update
Run the Helm deployment code
helm install  \
--set config.exporters.logzio.region=<<LOGZIO_ACCOUNT_REGION_CODE>> \
--set config.exporters.logzio.account_token=<<TRACING-SHIPPING-TOKEN>> \
logzio-otel-traces logzio-helm/logzio-otel-traces

Replace <<TRACING-SHIPPING-TOKEN>> with the token of the account you want to ship to.

If your account is hosted in any region other than us, replace <LOGZIO_ACCOUNT_REGION_CODE> with the applicable region code.

If your account is hosted in us, remove region: line from the config. <<LOGZIO_ACCOUNT_REGION_CODE>> - (Optional): Your logz.io account region code. Defaults to “us”. Required only if your logz.io region is different than US East.

Define the logzio-otel-traces dns name

In most cases, the dns name will be logzio-otel-traces.default.svc.cluster.local, where default is the namespace where you deployed the helm chart and svc.cluster.name is your cluster domain name.

If you are not sure what your cluster domain name is, you can run the following command to look it up:

kubectl run -it --image=k8s.gcr.io/e2e-test-images/jessie-dnsutils:1.3 --restart=Never shell -- \
sh -c 'nslookup kubernetes.default | grep Name | sed "s/Name:\skubernetes.default//"'

It will deploy a small pod that extracts your cluster domain name from your Kubernetes environment. You can remove this pod after it has returned the cluster domain name.

Download Java agent

Download the latest version of the OpenTelemetry Java agent to the host of your Java application.

Attach the agent to your java application

Add the following command to your Java application Dockerfile or equivalent:

java -javaagent:<path/to>/opentelemetry-javaagent-all.jar \
     -Dotel.traces.exporter=otlp \
     -Dotel.metrics.exporter=none \
     -Dotel.resource.attributes=service.name=<<YOUR-SERVICE-NAME>> \
     -Dotel.exporter.otlp.endpoint=http://<<logzio-otel-traces-service-dns>>:4317 \
     -jar target/*.jar
  • Replace <<path/to>> with the path to the directory where you downloaded the agent.
  • Replace <<YOUR-SERVICE-NAME>> with a name for your service under which it will appear in Logz.io Jaeger UI.
  • Replace <<logzio-otel-traces-service-dns>> with the OpenTelemetry collector service dns obtained previously (service IP is also allowed here).
Check Logz.io for your traces

Give your traces some time to get from your system to ours, then open Logz.io.

Customizing Helm chart parameters

Configure customization options

You can use the following options to update the Helm chart parameters:

  • Specify parameters using the --set key=value[,key=value] argument to helm install.

  • Edit the values.yaml.

  • Overide default values with your own my_values.yaml and apply it in the helm install command.

Example
helm install logzio-otel-traces logzio-helm/logzio-otel-traces -f my_values.yaml 

Uninstalling the Chart

The uninstall command is used to remove all the Kubernetes components associated with the chart and to delete the release.

To uninstall the logzio-otel-traces deployment, use the following command:

helm uninstall logzio-otel-traces