Appearance

OpenTelemetry Collector and Agents ​

OpenTelemetry is a Swiss Army knife for your app's health - minus the tiny, easy-to-lose toothpick. It's a collection of APIs, SDKs, standards, and tools to let you peek under the hood of your app, all without vendor lock-in.

This doc is focused on how to set up sending OpenTelemetry data to Datable from applications or from the OpenTelemetry collector.

Configuring the OpenTelemetry collector ​

Configuration can be configured in many ways. We are focused on modifying the src/opentelemetry file within your OpenTelemetry installation. Configuration is in two parts - setting up an exporter, and adding that exporter to your pipelines.

Exporter ​

Defining your exporter can be done two ways:

HTTP ​

yaml
exporters:
  otlphttp/datable:
    endpoint: https://YOUR_DATABLE_HOST.dtbl.io:4318
exporters:
  otlphttp/datable:
    endpoint: https://YOUR_DATABLE_HOST.dtbl.io:4318

gRPC ​

yaml
exporters:
  otlp/datable:
    endpoint: YOUR_DATABLE_HOST.dtbl.io:4317
exporters:
  otlp/datable:
    endpoint: YOUR_DATABLE_HOST.dtbl.io:4317

More examples are on the OTel website.

Pipeline ​

Whichever exporter you choose, gRPC or HTTP, you need to add to the exporters section of your pipeline. Adding both will result in data being duplicated and sent twice.

HTTP ​

yaml
service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlphttp/datable]
    logs:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlphttp/datable]
service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlphttp/datable]
    logs:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlphttp/datable]

gRPC ​

yaml
service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlp/datable]
    logs:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlp/datable]
service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlp/datable]
    logs:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlp/datable]

After configuration ​

Ensure you restart your OpenTelemetry Colletor and check to see if your logs are flowing into Datable.

Full example ​

This is the config we use for local development. It's worth calling out the debug exporter, which will display in standard out.

yaml
receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318
        cors:
          allowed_origins:
            - "http://*"
            - "https://*"

exporters:
  debug:
  otlphttp/datable:
    endpoint: "https://YOUR_DATABLE_HOST.dtbl.io:4318"

processors:
  batch:

connectors:
  spanmetrics:

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlphttp/datable, debug]
    logs:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlphttp/datable, debug]
receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318
        cors:
          allowed_origins:
            - "http://*"
            - "https://*"

exporters:
  debug:
  otlphttp/datable:
    endpoint: "https://YOUR_DATABLE_HOST.dtbl.io:4318"

processors:
  batch:

connectors:
  spanmetrics:

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlphttp/datable, debug]
    logs:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlphttp/datable, debug]

Instrumenting your applications with OpenTelemetry agents ​

Open Telemtry can be instrumented through a variety of means depending on the specific needs and application stack. See the OpenTelemetry Getting Started documentation for options and resources.

Tracing ​

Import the below file at the start of your application. It include auto-instrumentation, so the most common nodejs libraries will be automatically instrumented.

Below is the minimal snippet we use internally, and configure with ENV VARS.

typescript
/* tracer.ts */

import * as os from 'os'

import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node'
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-proto'
import { Resource } from '@opentelemetry/resources'
import * as opentelemetry from '@opentelemetry/sdk-node'
import { SemanticResourceAttributes } from '@opentelemetry/semantic-conventions'

const resource = new Resource({
  [SemanticResourceAttributes.SERVICE_NAME]: 'my-app',
  [SemanticResourceAttributes.SERVICE_VERSION]: '0.0.1',
  [SemanticResourceAttributes.SERVICE_NAMESPACE]: 'my-namespace',
  [SemanticResourceAttributes.HOST_NAME]: os.hostname(),
})

const spanCollectorOptions = {
  url: "https://YOUR_DATABLE_HOST.dtbl.io:4318/v1/traces",
};

const traceExporter = new OTLPTraceExporter(spanCollectorOptions)

const sdk = new opentelemetry.NodeSDK({
  resource,
  instrumentations: [getNodeAutoInstrumentations()],
  traceExporter: [traceExporter],
})

sdk.start()

process.on('SIGTERM', () => {
  sdk
    .shutdown()
    .then(
      () => console.log('SDK shut down successfully'),
      (err) => console.log('Error shutting down SDK', err)
    )
    .finally(() => process.exit(0))
})
/* tracer.ts */

import * as os from 'os'

import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node'
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-proto'
import { Resource } from '@opentelemetry/resources'
import * as opentelemetry from '@opentelemetry/sdk-node'
import { SemanticResourceAttributes } from '@opentelemetry/semantic-conventions'

const resource = new Resource({
  [SemanticResourceAttributes.SERVICE_NAME]: 'my-app',
  [SemanticResourceAttributes.SERVICE_VERSION]: '0.0.1',
  [SemanticResourceAttributes.SERVICE_NAMESPACE]: 'my-namespace',
  [SemanticResourceAttributes.HOST_NAME]: os.hostname(),
})

const spanCollectorOptions = {
  url: "https://YOUR_DATABLE_HOST.dtbl.io:4318/v1/traces",
};

const traceExporter = new OTLPTraceExporter(spanCollectorOptions)

const sdk = new opentelemetry.NodeSDK({
  resource,
  instrumentations: [getNodeAutoInstrumentations()],
  traceExporter: [traceExporter],
})

sdk.start()

process.on('SIGTERM', () => {
  sdk
    .shutdown()
    .then(
      () => console.log('SDK shut down successfully'),
      (err) => console.log('Error shutting down SDK', err)
    )
    .finally(() => process.exit(0))
})

Configuring the destination ​

ENV VARS ​

Exporters ​