feat: adding instana as a tracing backend (#3610)

* chore: add example of instana integration with otlp

* chore: add instana as a datastore

* chore: fixes on Instana

* add docs

* add .env sample

* update typos on tests

* fix doc broken link

* Apply suggestions from code review

Co-authored-by: Julianne Fermi <julianne@kubeshop.io>

---------

Co-authored-by: Julianne Fermi <julianne@kubeshop.io>

api/dataStores.yaml

@@ -208,6 +208,7 @@ components:
           signoz,
           dynatrace,
           sumologic,
+          instana
         ]
     SupportedClients:
       type: string

docs/docs/configuration/connecting-to-data-stores/instana.mdx

@@ -0,0 +1,116 @@
+---
+id: instana
+title: Instana
+description: Use Instana as the trace data store for Tracetest. Configure the OpenTelemetry Collector to receive traces and forward them to both Tracetest and Instana.
+keywords:
+  - tracetest
+  - trace-based testing
+  - observability
+  - distributed tracing
+  - testing
+image: https://res.cloudinary.com/djwdcmwdz/image/upload/v1698686403/docs/Blog_Thumbnail_14_rsvkmo.jpg
+---
+
+If you want to use [Instana](https://www.ibm.com/products/instana) as the trace data store, you'll configure the OpenTelemetry Collector to receive traces from your system and then send them to both Tracetest and Instana. And, you don't have to change your existing pipelines to do so.
+
+:::tip
+Examples of configuring Tracetest with Instana can be found in the [`examples` folder of the Tracetest GitHub repo](https://github.com/kubeshop/tracetest/tree/main/examples).
+:::
+
+## Configuring OpenTelemetry Collector to Send Traces to Both Instana and Tracetest
+
+In your OpenTelemetry Collector config file:
+
+- Set the `exporter` to `otlp/tracetest`.
+- Set the `endpoint` to your Tracetest instance on port `4317`.
+
+:::tip
+If you are running Tracetest with Docker, and Tracetest's service name is `tracetest`, then the endpoint might look like this `http://tracetest:4317`
+:::
+
+Additionally, add another config:
+
+- Set the `exporter` to `otlp/instana`.
+- Set the `endpoint` to use the same OTLP stack as your agents. The correct endpoints can be found [here](https://www.ibm.com/docs/en/instana-observability/current?topic=opentelemetry-sending-data-instana-backend).
+- Set the `headers` to have `x-instana-key` as key and a hash as value. This hash correspond to the `INSTANA_AGENT_KEY` value shown on Instana UI.
+
+```yaml
+# collector.config.yaml
+
+# If you already have receivers declared, you can just ignore
+# this one and still use yours instead.
+receivers:
+  otlp:
+    protocols:
+      http:
+      grpc:
+
+processors:
+  # This configuration is needed to guarantee that the data is sent correctly to Datadog
+  batch:
+    send_batch_max_size: 100
+    send_batch_size: 10
+    timeout: 10s
+
+exporters:
+  # OTLP for Tracetest
+  # Send traces to Tracetest.
+  # Read more in docs here: https://docs.tracetest.io/configuration/connecting-to-data-stores/opentelemetry-collector
+  otlp/tracetest:
+    endpoint: tracetest:4317
+    tls:
+      insecure: true
+
+  # Instana exporter
+  # One example on how to set up a collector configuration for Instana can be seen here:
+  # https://www.ibm.com/docs/en/instana-observability/current?topic=opentelemetry-sending-data-instana-backend
+  # You can replace the variables INSTANA_OTLP_GRPC_ENDPOINT and INSTANA_API_KEY for their respective values
+  # or declare them as environment variables where your Open Telemetry Collector is installed
+  otlp/instana:
+    endpoint: ${INSTANA_OTLP_GRPC_ENDPOINT}
+    headers:
+      x-instana-key: ${INSTANA_API_KEY}
+
+service:
+  pipelines:
+    traces/tracetest:
+      receivers: [otlp]
+      processors: [batch]
+      exporters: [otlp/tracetest] # exporter sending traces to your Tracetest instance
+    traces/instana:
+      receivers: [otlp]
+      processors: [batch]
+      exporters: [otlp/instana] # exporter sending traces to directly to Instana
+```
+
+## Configure Tracetest to Use Instana as a Trace Data Store
+
+Configure your Tracetest instance to expose an `otlp` endpoint to make it aware it will receive traces from the OpenTelemetry Collector. This will expose Tracetest's trace receiver on port `4317`.
+
+## Connect Tracetest to Instana with the Web UI
+
+In the Web UI, (1) open Settings, and, on the (2) Tracing Backend tab, select (3) Datadog.
+
+![Instana](../img/configure-instana.png)
+
+## Connect Tracetest to Instana with the CLI
+
+Or, if you prefer using the CLI, you can use this file config.
+
+```yaml
+type: DataStore
+spec:
+  name: Instana pipeline
+  type: instana
+  default: true
+```
+
+Proceed to run this command in the terminal and specify the file above.
+
+```bash
+tracetest apply datastore -f my/data-store/file/location.yaml
+```
+
+{/*
+TODO: when the Instana tutorial is released, add link to learn more here
+*/}

examples/quick-start-instana-nodejs/.env.sample

@@ -0,0 +1,2 @@
+INSTANA_OTLP_GRPC_ENDPOINT= # use one of the Instana OTLP endpoints
+INSTANA_API_KEY=... # add Instana Agent Key here

examples/quick-start-instana-nodejs/.gitignore

@@ -0,0 +1,3 @@
+node_modules
+.DS_Store
+.env

examples/quick-start-instana-nodejs/api/Dockerfile

@@ -0,0 +1,11 @@
+FROM node:slim
+WORKDIR /usr/src/app
+
+COPY package*.json ./
+
+RUN npm install
+COPY . .
+
+EXPOSE 8080
+
+CMD [ "npm", "run", "with-grpc-tracer" ]

examples/quick-start-instana-nodejs/api/app.js

@@ -0,0 +1,10 @@
+const express = require("express")
+const app = express()
+app.get("/", (req, res) => {
+  setTimeout(() => {
+    res.send("Hello World")
+  }, 1000);
+})
+app.listen(8080, () => {
+  console.log(`Listening for requests on http://localhost:8080`)
+})

examples/quick-start-instana-nodejs/api/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "quick-start-nodejs",
+  "version": "1.0.0",
+  "description": "",
+  "main": "app.js",
+  "scripts": {
+    "with-grpc-tracer":"node -r ./tracing.otel.grpc.js app.js",
+    "with-http-tracer":"node -r ./tracing.otel.http.js app.js"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "dependencies": {
+    "@opentelemetry/auto-instrumentations-node": "^0.33.1",
+    "@opentelemetry/exporter-trace-otlp-grpc": "^0.34.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.33.0",
+    "@opentelemetry/sdk-node": "^0.33.0",
+    "express": "^4.18.2"
+  }
+}

examples/quick-start-instana-nodejs/api/tracing.otel.grpc.js

@@ -0,0 +1,10 @@
+const opentelemetry = require('@opentelemetry/sdk-node')
+const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node')
+const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-grpc');
+
+const sdk = new opentelemetry.NodeSDK({
+  traceExporter: new OTLPTraceExporter({ url: 'http://otel-collector:4317' }),
+  instrumentations: [getNodeAutoInstrumentations()],
+  serviceName: 'quick-start-nodejs'
+})
+sdk.start()

examples/quick-start-instana-nodejs/api/tracing.otel.http.js

@@ -0,0 +1,9 @@
+const opentelemetry = require('@opentelemetry/sdk-node')
+const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node')
+const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-http')
+
+const sdk = new opentelemetry.NodeSDK({
+  traceExporter: new OTLPTraceExporter({ url: 'http://otel-collector:4318/v1/traces' }),
+  instrumentations: [getNodeAutoInstrumentations()],
+})
+sdk.start()

examples/quick-start-instana-nodejs/docker-compose.yaml

@@ -0,0 +1,61 @@
+version: '3'
+services:
+  app:
+    image: quick-start-nodejs
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
+    build: ./api
+    ports:
+      - "8080:8080"
+
+  tracetest:
+    restart: unless-stopped
+    image: kubeshop/tracetest:${TAG:-latest}
+    platform: linux/amd64
+    ports:
+      - 11633:11633
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
+    volumes:
+      - type: bind
+        source: ./tracetest/tracetest.config.yaml
+        target: /app/tracetest.yaml
+      - type: bind
+        source: tracetest/tracetest-provision.yaml
+        target: /app/provision.yaml
+    command: --provisioning-file /app/provision.yaml
+    healthcheck:
+      test: ["CMD", "wget", "--spider", "localhost:11633"]
+      interval: 1s
+      timeout: 3s
+      retries: 60
+    depends_on:
+      postgres:
+        condition: service_healthy
+      otel-collector:
+        condition: service_started
+    environment:
+      TRACETEST_DEV: ${TRACETEST_DEV}
+
+  postgres:
+    image: postgres:14
+    environment:
+      POSTGRES_PASSWORD: postgres
+      POSTGRES_USER: postgres
+    healthcheck:
+      test: pg_isready -U "$$POSTGRES_USER" -d "$$POSTGRES_DB"
+      interval: 1s
+      timeout: 5s
+      retries: 60
+
+  otel-collector:
+    image: otel/opentelemetry-collector-contrib:0.92.0
+    restart: unless-stopped
+    command:
+      - "--config"
+      - "/otel-local-config.yaml"
+    environment:
+      INSTANA_OTLP_GRPC_ENDPOINT: ${INSTANA_OTLP_GRPC_ENDPOINT}
+      INSTANA_API_KEY: ${INSTANA_API_KEY}
+    volumes:
+      - ./tracetest/collector.config.yaml:/otel-local-config.yaml

examples/quick-start-instana-nodejs/test-api.yaml

@@ -0,0 +1,18 @@
+type: Test
+spec:
+  id: W656Q0c4g
+  name: http://app:8080
+  description: Calling Hello World API
+  trigger:
+    type: http
+    httpRequest:
+      url: http://app:8080
+      method: GET
+      headers:
+      - key: Content-Type
+        value: application/json
+  specs:
+  - selector: span[tracetest.span.type="http" name="GET /" http.target="/" http.method="GET"]
+    assertions:
+    - attr:http.status_code = 200
+    - attr:tracetest.span.duration < 2s

examples/quick-start-instana-nodejs/tracetest/collector.config.yaml

@@ -0,0 +1,37 @@
+receivers:
+  otlp:
+    protocols:
+      http:
+      grpc:
+
+processors:
+  batch:
+    send_batch_max_size: 100
+    send_batch_size: 10
+    timeout: 10s
+
+exporters:
+  # OTLP for Tracetest
+  otlp/tracetest:
+    endpoint: tracetest:4317 # Send traces to Tracetest. Read more in docs here:  https://docs.tracetest.io/configuration/connecting-to-data-stores/opentelemetry-collector
+    tls:
+      insecure: true
+
+  # Instana exporter
+  # One example on how to set up a collector configuration for Instana can be seen here:
+  # https://www.ibm.com/docs/en/instana-observability/current?topic=opentelemetry-sending-data-instana-backend
+  otlp/instana:
+    endpoint: ${INSTANA_OTLP_GRPC_ENDPOINT}
+    headers:
+      x-instana-key: ${INSTANA_API_KEY}
+
+service:
+  pipelines:
+    traces/tracetest:
+      receivers: [otlp]
+      processors: [batch]
+      exporters: [otlp/tracetest]
+    traces/instana:
+      receivers: [otlp]
+      processors: [batch]
+      exporters: [otlp/instana]

examples/quick-start-instana-nodejs/tracetest/tracetest-provision.yaml

@@ -0,0 +1,7 @@
+---
+type: DataStore
+spec:
+  id: current
+  name: Instana
+  type: instana
+  default: true

examples/quick-start-instana-nodejs/tracetest/tracetest.config.yaml

@@ -0,0 +1,21 @@
+postgres:
+  host: postgres
+  user: postgres
+  password: postgres
+  port: 5432
+  dbname: postgres
+  params: sslmode=disable
+
+telemetry:
+  exporters:
+    collector:
+      serviceName: tracetest
+      sampling: 100
+      exporter:
+        type: collector
+        collector:
+          endpoint: otel-collector:4317
+
+server:
+  telemetry:
+    exporter: collector