Quick Start Tutorial

The following tutorial will guide you through setting up a SkyWalking OAP with BanyanDB as the storage backend using Docker Compose. It is a quick way to get started with BanyanDB if you are a SkyWalking user and want to try out BanyanDB.

Option 1: Use the Docker Compose Example (Recommended)

This repository includes a ready-to-use docker-compose file at docker-compose.yaml that sets up:

BanyanDB - Standalone instance with property-based schema registry
SkyWalking OAP - Configured to use BanyanDB as storage
SkyWalking UI - Web interface for visualizing traces, metrics, and topology
Demo Services - Sample microservices that generate trace traffic automatically

Prerequisites

Docker Engine 20.10+
Docker Compose v2.0+

Quick Start

Navigate to the quick-start directory:
```
cd docs/guides/quick-start
```
Start the stack:
```
docker compose up -d
```
Wait for all services to be healthy (may take 1-2 minutes):
```
docker compose ps
```

Accessing the Services

Service	URL	Description
SkyWalking UI	http://localhost:8080	Web interface for traces, metrics, topology
BanyanDB HTTP	http://localhost:17913	HTTP endpoint for bydbctl and embedded UI
BanyanDB UI	http://localhost:17913	Embedded UI for querying data
OAP HTTP	http://localhost:12800	OAP REST API
OAP gRPC	localhost:11800	gRPC endpoint for agents

Verifying the Setup

Check BanyanDB is healthy:
```
nc -z localhost 17913
```

Check OAP is healthy:

docker logs skywalking-oap 2>&1 | grep "Health status"

View traces in SkyWalking UI:
- Open http://localhost:8080
- Go to “General” > “Service” to see the demo services
- Go to “Traces” to view trace data

Configuration

The docker-compose.yaml includes environment variables for customization:

# BanyanDB configuration
command: standalone

# SkyWalking OAP with BanyanDB storage
environment:
  SW_STORAGE: banyandb
  SW_STORAGE_BANYANDB_TARGETS: banyandb:17912

  # Enable VM metrics collection
  SW_OTEL_RECEIVER: default
  SW_OTEL_RECEIVER_ENABLED_OC_RULES: vm
  SW_OTEL_RECEIVER_ENABLED_OTEL_METRICS_RULES: vm

Environment Variables

You can customize the deployment using environment variables:

# Use specific image versions
BANYANDB_IMAGE=apache/skywalking-banyandb:0.9.0 \
OAP_IMAGE=apache/skywalking-oap-server:10.3.0 \
OAP_UI_IMAGE=apache/skywalking-ui:10.3.0 \
docker compose up -d

Stopping the Stack

docker compose down

To also remove data volumes:

docker compose down -v

Option 2: Use SkyWalking Showcase

Clone the showcase repository to use their pre-configured demo:

git clone https://github.com/apache/skywalking-showcase.git
cd skywalking-showcase

Start the showcase cluster:

make deploy.docker FEATURE_FLAGS=single-node,agent

You could find the details of the showcase cluster in the SkyWalking Showcase

Data Presentation

Using Docker Compose (Option 1)

Access the UIs at:

SkyWalking UI: http://localhost:8080
BanyanDB UI: http://localhost:17913

Using Showcase (Option 2)

SkyWalking UI: http://localhost:9999
BanyanDB UI: http://localhost:17913

We can view the final presentation of the metrics/traces/logs/topology for the demo system on the UI dashboards. The following image shows the General-Service service list in the SkyWalking UI:

Query the Data in BanyanDB

If you are interested in the raw data stored in BanyanDB, you can use the BanyanDB embedded UI or BanyanDB CLI(bydbctl) to query the data.

BanyanDB embedded UI can be accessed at http://localhost:17913. The following image shows how to query all the services from the BanyanDB:

BanyanDB CLI(bydbctl) can be used to query the data from the command line.

bydbctl measure query -f - <<EOF
name: "service_traffic_minute"
groups: ["index"]
tagProjection:
  tagFamilies:
    - name: "default"
      tags: ["service_id", "short_name","layer"]
EOF

We can see the following output:

dataPoints:
- fields: []
  sid: "6694704579998440084"
  tagFamilies:
  - name: default
    tags:
    - key: service_id
      value:
        str:
          value: Z2F0ZXdheQ==.1
    - key: short_name
      value:
        str:
          value: gateway
    - key: layer
      value:
        int:
          value: "2"
  timestamp: "2025-02-23T12:36:00Z"
  version: "9017360854805676"
- fields: []
  sid: "2264252405119611112"
  tagFamilies:
  - name: default
    tags:
    - key: service_id
      value:
        str:
          value: R3VhdmFDYWNoZS1sb2NhbA==.0
    - key: short_name
      value:
        str:
          value: GuavaCache-local
    - key: layer
      value:
        int:
          value: "19"
  timestamp: "2025-02-23T12:36:00Z"
  version: "9017360854808916"
- fields: []
  sid: "7200167536615717650"
  tagFamilies:
  - name: default
    tags:
    - key: service_id
      value:
        str:
          value: Z2F0ZXdheQ==.1
    - key: short_name
      value:
        str:
          value: gateway
    - key: layer
      value:
        int:
          value: "39"
  timestamp: "2025-02-23T12:36:00Z"
  version: "9017360854811805"
- fields: []
  sid: "11101904457842605307"
  tagFamilies:
  - name: default
    tags:
    - key: service_id
      value:
        str:
          value: YWdlbnQ6OmZyb250ZW5k.1
    - key: short_name
      value:
        str:
          value: frontend
    - key: layer
      value:
        int:
          value: "2"
  timestamp: "2025-02-23T12:36:00Z"
  version: "9017360854814505"
- fields: []
  sid: "16886997253576549432"
  tagFamilies:
  - name: default
    tags:
    - key: service_id
      value:
        str:
          value: c29uZ3M=.1
    - key: short_name
      value:
        str:
          value: songs
    - key: layer
      value:
        int:
          value: "2"
  timestamp: "2025-02-23T12:36:00Z"
  version: "9017360854817476"
- fields: []
  sid: "3060777112302363794"
  tagFamilies:
  - name: default
    tags:
    - key: service_id
      value:
        str:
          value: YXBw.1
    - key: short_name
      value:
        str:
          value: app
    - key: layer
      value:
        int:
          value: "2"
  timestamp: "2025-02-23T12:36:00Z"
  version: "9017360854820076"
- fields: []
  sid: "3424504874722446951"
  tagFamilies:
  - name: default
    tags:
    - key: service_id
      value:
        str:
          value: c29uZ3M=.1
    - key: short_name
      value:
        str:
          value: songs
    - key: layer
      value:
        int:
          value: "39"
  timestamp: "2025-02-23T12:36:00Z"
  version: "9017360854823045"
- fields: []
  sid: "7814002932715409293"
  tagFamilies:
  - name: default
    tags:
    - key: service_id
      value:
        str:
          value: cmF0aW5n.1
    - key: short_name
      value:
        str:
          value: rating
    - key: layer
      value:
        int:
          value: "2"
  timestamp: "2025-02-23T12:36:00Z"
  version: "9017360854827145"
- fields: []
  sid: "4722671161330384377"
  tagFamilies:
  - name: default
    tags:
    - key: service_id
      value:
        str:
          value: YWdlbnQ6OnVp.1
    - key: short_name
      value:
        str:
          value: ui
    - key: layer
      value:
        int:
          value: "10"
  timestamp: "2025-02-23T12:36:00Z"
  version: "9017360854831856"
- fields: []
  sid: "5033399348250958164"
  tagFamilies:
  - name: default
    tags:
    - key: service_id
      value:
        str:
          value: bG9jYWxob3N0Oi0x.0
    - key: short_name
      value:
        str:
          value: localhost:-1
    - key: layer
      value:
        int:
          value: "14"
  timestamp: "2025-02-23T12:36:00Z"
  version: "9017360854839325"
- fields: []
  sid: "6492992516036642565"
  tagFamilies:
  - name: default
    tags:
    - key: service_id
      value:
        str:
          value: MTcyLjE5LjAuNDo2MTYxNg==.0
    - key: short_name
      value:
        str:
          value: 172.19.0.4:61616
    - key: layer
      value:
        int:
          value: "15"
  timestamp: "2025-02-23T12:36:00Z"
  version: "9017360854846096"
- fields: []
  sid: "724075540118355969"
  tagFamilies:
  - name: default
    tags:
    - key: service_id
      value:
        str:
          value: cmVjb21tZW5kYXRpb24=.1
    - key: short_name
      value:
        str:
          value: recommendation
    - key: layer
      value:
        int:
          value: "2"
  timestamp: "2025-02-23T12:36:00Z"
  version: "9017360854850545"
trace: null

Edit this page