Run Aidbox with OpenTelemetry locally

Get up-to-speed with Aidbox observability features via interactive tutorials.

Intro

This guide helps you to launch and explore the Aidbox observability features locally.

It introduces you to:

• The Aidbox installation process with Docker & Docker Compose,

• Logs & metrics & traces exporting to Elasticsearch & Prometheus & Zipkin using OpenTelemetry collector service.

Please make sure that both Docker & Docker Compose are installed.

Quickstart Guide

1. Get the Aidbox License for self-hosting

Create the Aidbox License for the 14-day trial period on https://aidbox.app/, select self-hosted, or use the license that you already have.

The Aidbox License Key will be required in the next step, where we will prepare the configuration for Aidbox.

2. Configure the Aidbox

Aidbox is configured by dedicated Aidbox Configuration Projects.

You can start with the default configuration project published on our GitHub and customize it for your specific needs later. Select the FHIR version and clone the corresponding project with the Bash commands below:

git clone \
  --branch=open-telemetry-fhir-r5 \
  --depth=1 \
  https://github.com/Aidbox/aidbox-project-template.git \
  aidbox-project && \
  cd aidbox-project && \
  rm -rf .git

Here is the basic structure of the Aidbox Configuration Project:

aidbox-project/
├── .env
├── docker-compose.yaml
├── open-telemetry-config.yaml
├── prometheus
│   └── prometheus.yml
├── grafana
│   └── datasources
│       └── all.yaml
├── zen-package.edn
└── zrc/
    ├── config.edn
    └── main.edn

Aidbox Configuration Projects

Everything in Aidbox can be configured with a dedicated Aidbox Configuration Project from the FHIR version definition to enabling add-on modules.

This approach helps you keep configurations under a version control system and share them between Aidbox Instances.

Learn more.

Add the license key to your configuration project.

Update the .env file within your configuration project with the Aidbox License Key from Step 1:

.env

AIDBOX_LICENSE=YOUR_AIDBOX_LICENSE_KEY

PGHOSTPORT=5437
PGUSER=postgres
...

3. Start Aidbox with Docker Compose

Start Aidbox with Docker Compose:

docker compose up --force-recreate

Navigate to http://localhost:8888/ and Sign In to the Aidbox UI using the login admin and password password.

4. Discover Aidbox logs with Kibana

Kibana should be available on http://localhost:5602 address. To see logs in Kibana we should

• make sure that logs are coming to Elasticsearch and then

• create a data view to observe over logs.

Go to Index Management page in Kibana (Menu → Stack Management → Index Management). You should see aidbox_logs index there.

Index management page

Then we shoould go to Data Views page (Menu → Stack Management → Data Views) and create a data view there.

Data view creation

Then go to Discover page (Menu → Discover) and observe your logs.

Log discover page

5. Discover Aidbox metrics with Prometheus

Prometheus should be available on http://localhost:9090 address. To see metrics in Prometheus we should open it and search for it.

Prometheus UI

6. Discover Aidbox traces with Zipkin

Zipkin should be available on http://localhost:9411/ address. To see traces in Zipkin click the Run query button.

Traces list in Zipkin

Click the Show button to see all spans of a certain request.

Trace view in Zipkin

Next Steps

• Learn more about Aidbox Configuration