Send traces from your Zipkin installation to Logz.io

• Overview
• Local host
• Troubleshooting

Deploy this integration to send traces from your Zipkin installation to Logz.io.

Logz.io recommends that you use OpenTelemetry to gather trace transaction data from your system. Because of its versatility, OpenTelemetry has been widely adopted as the industry standard: OpenTelemetry can be equipped with many additional functionalities, one of which is collecting aggregated trace data. Beyond that, OpenTelemetry is set to be the best production-ready solution going forward.

Architecture overview

This integration includes:

• Installing the OpenTelemetry collector with Logz.io exporter on your application host
• Configuring the collector to receive traces from your Zipkin installation and send them to Logz.io

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

Set up your locally hosted Zipkin installation to send traces to Logz.io

Before you begin, you’ll need:

• An application instrumented with Zipkin
• An active account with Logz.io

This integration uses OpenTelemetry Collector Contrib, not the OpenTelemetry Collector Core.

Download and configure OpenTelemetry collector

Create a dedicated directory on the host of your 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:
  zipkin:
    endpoint: "0.0.0.0:9411"


exporters:
  logzio/traces:
    account_token: "<<TRACING-SHIPPING-TOKEN>>"
    region: "<<LOGZIO_ACCOUNT_REGION_CODE>>"

processors:
  batch:
  tail_sampling:
    policies:
      [
        {
          name: policy-errors,
          type: status_code,
          status_code: {status_codes: [ERROR]}
        },
        {
          name: policy-slow,
          type: latency,
          latency: {threshold_ms: 1000}
        }, 
        {
          name: policy-random-ok,
          type: probabilistic,
          probabilistic: {sampling_percentage: 10}
        }        
      ]

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

service:
  extensions: [health_check, pprof, zpages]
  pipelines:
    traces:
      receivers: [zipkin]
      processors: [batch]
      exporters: [logzio/traces]

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

Replace <LOGZIO_ACCOUNT_REGION_CODE> with the applicable region code.

The tail_sampling defines the decision to sample a trace after the completion of all the spans in a request. By default, this configuration collects all traces that have a span that was completed with an error, all traces that are slower than 1000 ms, and 10% of the rest of the traces.

You can add more policy configurations to the processor. For more on this, refer to OpenTelemetry Documentation.

The configurable parameters in the Logz.io default configuration are:

Parameter	Description	Default
threshold_ms	Threshold for the spand latency - all traces slower than the threshold value will be filtered in.	1000
sampling_percentage	Sampling percentage for the probabilistic policy.	10

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.

Run the application

Run the application to generate traces.

Check Logz.io for your traces

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

This section contains some guidelines for handling errors that you may encounter when trying to collect traces with OpenTelemetry.

• Architecture overview
• Set up your locally hosted Zipkin installation to send traces to Logz.io
  • Download and configure OpenTelemetry collector
  • Start the collector
  • Run the application
  • Check Logz.io for your traces
• Problem: No traces are sent
  • Possible cause - Collector path not configured
  • Possible cause - Wrong exporter/protocol/endpoint
  • Possible cause - Collector failure
  • Possible cause - Exporter failure
  • Possible cause - Receiver failure

Problem: No traces are sent

The code has been instrumented, but the traces are not being sent.

Possible cause - Collector not installed

The OpenTelemetry collector may not be installed on your system.

Suggested remedy

Check if you have an OpenTelemetry collector installed and configured to receive traces from your hosts.

Possible cause - Collector path not configured

If the collector is installed, it may not have the correct endpoint configured for the receiver.

Suggested remedy

1. Check that the configuration file of the collector lists the following endpoints:

   receivers:
     otlp:
       protocols:
         grpc:
           endpoint: "0.0.0.0:4317"
         http:
           endpoint: "0.0.0.0:4318"
   

2. In the instrumentation code, make sure that the endpoint is specified correctly. Refer to our tracing documentation for more on this.

Possible cause - Traces not genereated

If the collector is installed and the endpoints are properly configured, the instrumentation code may be incorrect.

Suggested remedy

1. Check if the instrumentation can output traces to a console exporter.
2. Use a web-hook to check if the traces are going to the output.
3. Use the metrics endpoint of the collector (http://<>:8888/metrics) to see the number of spans received per receiver and the number of spans sent to the Logz.io exporter.

• Replace <<COLLECTOR-HOST>> with the address of your collector host, e.g. localhost, if the collector is hosted locally.

If the above steps do not work, refer to our tracing documentation and re-instrument the application.

Possible cause - Wrong exporter/protocol/endpoint

If traces are generated but not send, the collector may be using incorrect exporter, protocol and/or endpoint.

The correct endpoints are:

   receivers:
     otlp:
       protocols:
         grpc:
           endpoint: "<<COLLECTOR-URL>>:4317"
         http:
           endpoint: "<<COLLECTOR-URL>>:4318/v1/traces"

Suggested remedy

1. Activate debug logs in the configuration file of the collector as follows:

   service:
     telemetry:
       logs:
         level: "debug"
   

Debug logs indicate the status code of the http/https post request.

If the post request is not successful, check if the collector is configured to use the correct exporter, protocol, and/or endpoint.

If the post request is successful, there will be an additional log with the status code 200. If the post request failed for some reason, there would be another log with the reason for the failure.

Possible cause - Collector failure

If the debug logs are sent, but the traces are still not generated, the collector logs need to be investigated.

Suggested remedy

1. On Linux and MacOS, see the logs for the collector:

   journalctl | grep otelcol
   

   To only see errors:

   journalctl | grep otelcol | grep Error
   

2. Otherwise, navigate to the following URL - http://localhost:8888/metrics

This is the endpoint to access the collector metrics in order to see different events that might happen within the collector - receiving spans, sending spans as well as other errors.

Possible cause - Exporter failure

Traces may not be generated if the exporter is not configured properly.

Suggested remedy

If you are unable to export traces to a destination, this may be caused by the following:

• There is a network configuration issue
• The exporter configuration is incorrect
• The destination is unavailable

To investigate this issue:

1. Make sure that the exporters and service: pipelines are configured correctly.
2. Check the collector logs as well as zpages for potential issues.
3. Check your network configuration, such as firewall, DNS, or proxy.

For example, those metrics can provide information about the exporter:

# HELP otelcol_exporter_enqueue_failed_metric_points Number of metric points failed to be added to the sending queue.

# TYPE otelcol_exporter_enqueue_failed_metric_points counter
otelcol_exporter_enqueue_failed_metric_points{exporter="logging",service_instance_id="0582dab5-efb8-4061-94a7-60abdc9867e1",service_version="latest"} 0

Possible cause - Receiver failure

Traces may not be generated if the receiver is not configured properly.

Suggested remedy

If you are unable to receive data, this may be caused by the following:

• There is a network configuration issue
• The receiver configuration is incorrect
• The receiver is defined in the receivers section, but not enabled in any pipelines
• The client configuration is incorrect

Those metrics can provide about the receiver:

# HELP otelcol_receiver_accepted_spans Number of spans successfully pushed into the pipeline.

# TYPE otelcol_receiver_accepted_spans counter
otelcol_receiver_accepted_spans{receiver="otlp",service_instance_id="0582dab5-efb8-4061-94a7-60abdc9867e1",service_version="latest",transport="grpc"} 34


# HELP otelcol_receiver_refused_spans Number of spans that could not be pushed into the pipeline.

# TYPE otelcol_receiver_refused_spans counter
otelcol_receiver_refused_spans{receiver="otlp",service_instance_id="0582dab5-efb8-4061-94a7-60abdc9867e1",service_version="latest",transport="grpc"} 0