Skip to main content

Quickstart with MITM proxy

This quickstart guide helps you evaluate API Observability on macOS or Windows using MITM proxy

Levo Sensor Package for macOS/Windows

Because macOS and Windows do not support eBPF, Levo provides a Docker-based Sensor package for quick evaluation on these platforms. This Sensor package observes API traffic by reverse proxying requests between your API Client and API Server.

Estimated completion time: 10 minutes.

1. Prerequisites​

  • Docker Engine version 18.03.0 or later
  • Admin (or sudo) privileges on the Docker host
  • Levo.ai account
  • Command-line terminal with Bash or a Bash-compatible shell

2. Set up a test API service​

API Observability auto-discovers APIs and generates OpenAPI specifications by observing traffic between your API Client and API Server.

If you do not have a test API Service/Application, you can use the sample application provided by Levo.

  • a. Note down the base URL for your test API Server/Service.

    For example, if you are running the sample application (crAPI) on your laptop, the base URL would be http://localhost:8888. If your local test API Server uses HTTPS, the base URL would be https://localhost/.

    Since the Sensor package runs in a container, addresses like localhost or 127.0.0.1 that refer to the Docker host must be translated to ones that can be resolved inside the container. Use host.docker.internal instead of localhost or 127.0.0.1 in the base URL.

    In essence, if your base URL is http://localhost:<port> or http://127.0.0.1:<port>, specify http://host.docker.internal:<port> below.

  • b. Export your API Server/Service URL in your terminal.

export SERVICE_ADDRESS=<http://YOUR_HOST:YOUR_PORT/YOUR_BASE_PATH>

3. Copy Authorization Key from Levo.ai​

The Sensor package uses an authorization key to access Levo.ai. Follow the steps below to copy and export the key.

  • Log in to Levo.ai.
  • Click your user profile.
  • Click User Settings.
  • Click Keys in the left navigation.
  • Click Get Satellite Authorization Key.
  • Copy your authorization key.
  • Export the copied Authorization Key in your terminal.
export LEVOAI_AUTH_KEY=<'Authorization Key' copied above>

4. Pick an Application Name​

Auto-discovered API endpoints and their OpenAPI specifications are shown in the API Catalog, grouped under an application name. The application name helps segregate and group API endpoints from different API servers, similar to how folders work in an operating system.

  • a. Pick a descriptive name that will be used in the subsequent step below. For example: my-test-api-server.
  • b. Export the Application Name in your terminal.
export LEVOAI_SERVICE_NAME=<'Application Name' chosen above>

5. Download the Docker Compose file​

Execute the following in your terminal:

Loading...

If you prefer to download the Docker Compose file via your browser, you can download it

Loading...
.

6. Install the Sensor package with Docker Compose​

Execute the following in your terminal (where you previously downloaded the Docker Compose file):

docker compose -f proxy-docker-compose.yml pull && docker compose -f proxy-docker-compose.yml up -d

7. Verify connectivity with Levo.ai​

The Sensor package includes both the proxy-based Sensor and the Satellite. Follow the steps below to check Satellite health and connectivity to Levo.ai.

a. Check Satellite health​

The Satellite is comprised of four subcomponents: 1) levoai-collector, 2) levoai-rabbitmq, 3) levoai-satellite, and 4) levoai-tagger.

Wait a couple of minutes after the install, then check the health of the components by running:

docker ps -f name=levoai

If the Satellite is healthy, you should see output similar to below.

CONTAINER ID   IMAGE                        COMMAND                   CREATED          STATUS                    PORTS                                                                                                         NAMES
5a54d8efe672   levoai/proxy:latest          "docker-entrypoint.s..."   50 seconds ago   Up 37 seconds              0.0.0.0:8081->8081/tcp, 0.0.0.0:9080->8080/tcp                                                                levoai-proxy
8767c62db6cb   levoai/satellite:latest      "python -OO /opt/lev..."   50 seconds ago   Up 37 seconds                                                                                                   levoai-tagger
dcb187e00ff2   levoai/satellite:latest      "gunicorn --capture-..."   50 seconds ago   Up 37 seconds             0.0.0.0:9999->9999/tcp                                                                                        levoai-satellite
169ceecf0263   rabbitmq:3.10.5-management   "docker-entrypoint.s..."   50 seconds ago   Up 49 seconds (healthy)   4369/tcp, 5671/tcp, 0.0.0.0:5672->5672/tcp, 15671/tcp, 15691-15692/tcp, 25672/tcp, 0.0.0.0:15672->15672/tcp   levoai-rabbitmq

b. Check connectivity​

Execute the following to check for connectivity health:

docker logs levoai-tagger 2>&1 | grep "Ready to process; waiting for messages."

If connectivity is healthy, you will see output similar to below:

{"level": "info", "time": "2022-06-07 08:07:22,439",
"line": "rabbitmq_client.py:155", "version": "fc628b50354bf94e544eef46751d44945a2c55bc",
"module": "/opt/levoai/e7s/src/python/levoai_e7s/satellite/rabbitmq_client.py",
"message": "Ready to process; waiting for messages."}

Please contact support@levo.ai if you notice health- or connectivity-related errors.

8. Generate application traffic​

The Sensor picks up API traffic that is HTTP/1.x based. You need consistent traffic on your API endpoints for them to be auto-discovered and documented.

a. Point your API Client to the Sensor​

The Sensor acts as a reverse proxy for your API Server. You need to point your API Client to the Sensor, which will proxy traffic to your test API Server/Service.

The Sensor listens on http://127.0.0.1:9080. Point your API client (web browser, Postman, curl, and so on) to this address instead of the API Server address.

If your API Server uses HTTPS (TLS), the Sensor will use HTTPS when proxying traffic to it. Your API Client must still use HTTP when talking to the Sensor.

If you are using /etc/hosts (or the equivalent on Windows) to resolve the IP address of your API Server, edit the appropriate entry to point to 127.0.0.1 (the Sensor IP address).

b. Generate traffic​

Exercise your API endpoints several times using your API Client. Use a load generator to generate consistent traffic if needed.

c. Verify API traffic capture​

Check the logs of the Satellite Tagger subcomponent.

docker logs levoai-tagger 2>&1 | grep "Consuming the span"

If API traffic is being processed correctly, you will see log entries containing Consuming the span.

9. View auto-discovered OpenAPI specifications​

The API Catalog in Levo.ai should be auto-populated within a few minutes after your API endpoints are exercised consistently.

The API Catalog will contain your auto-discovered API endpoints and their OpenAPI schemas, all grouped under the Application Name you chose earlier.

Congratulations! You have successfully auto-discovered and auto-documented API endpoints in your application.


Common tasks​

Shut down the Sensor​

Execute the following in the directory where you downloaded the Docker Compose file:

docker compose -f proxy-docker-compose.yml down

Change the Sensor listen port​

The Sensor listens on TCP port 9080 (interface address 127.0.0.1) by default. If this conflicts with a port used by another application, you can change it by following the instructions below.

  • Shut down the Sensor (if running)
  • Export your desired port in your terminal
export LEVOAI_PROXY_PORT=<Your desired port number>