Demo application

This is a demo Android application to show how the EDOT Android agent works.

To showcase an end-to-end scenario including distributed tracing we'll instrument this demo weather application that comprises two Android screens and a simple local backend service based on Spring Boot.

By running it, you can explore how EDOT Android captures and correlates telemetry from a mobile app:

• Distributed traces that connect Android user actions with backend HTTP requests.
• Custom spans and logs from the Android app.
• An intentional backend error path.
• An intentional Android crash that appears in Kibana after relaunching the app.

Table of contents

• Components
  • Backend service
  • Android application
  • EDOT Collector
• How to run
  • Prerequisites
  • Step 1: Setting up Elasticsearch, Kibana and the EDOT Collector
  • Step 2: Launching the backend service
  • Step 3: Launch the Android application
• Analyzing the data

Components

Backend service

Located in the backend module. This is a simple local backend service based on Spring Boot that provides APIs for the application and helps showcasing the the distributed tracing use case.

Android application

Located in the app module. The first screen has a dropdown list of city names and a button that takes you to the second one, where you'll see the selected city's current temperature. If you pick a non-European city on the first screen, you'll get an error from the (local) backend when you head to the second screen. This is to demonstrate how network and backend errors are captured and correlated. The floating action button intentionally crashes the app so you can also inspect Android crash reporting in Kibana.

EDOT Collector

The EDOT Collector (Elastic Distribution of the OpenTelemetry Collector) receives telemetry data from both the Android application and the backend service and forwards it to Elasticsearch for storage and analysis. In this demo, it is set up automatically as part of Step 1 via start-local.

How to run

Prerequisites

• Java 17 or higher.
• Docker.
• An Android emulator.
• On Microsoft Windows use Windows Subsystem for Linux (WSL).

Note

The reason why is recommended using an emulator is because the endpoints set here and here point to local services via the emulator's localhost IP (10.0.2.2). If you wanted to use a real device, you'd need to replace the 10.0.2.2 host by the one of the machine where you'll start the services mentioned in the steps below.

Step 1: Setting up Elasticsearch, Kibana and the EDOT Collector

We use start-local to spin up Elasticsearch, Kibana and the EDOT Collector locally with a single command. Run the following:

curl -fsSL https://elastic.co/start-local | sh -s -- --edot

This creates an elastic-start-local folder and starts all three services. Once it finishes, the EDOT Collector endpoint will be http://localhost:4318.

You don't need to configure the EDOT Collector endpoint for this demo application, as it has already been set here.

You can stop and start the services later with the scripts in the elastic-start-local folder:

cd elastic-start-local
./stop.sh   # stop the services
./start.sh  # start them again

For more information on start-local, refer to the start-local documentation.

Step 2: Launching the backend service

We're going to use the backend-manager script, which will build the backend, package it in a Docker image and run it connected to the same network as the EDOT Collector.

Once the backend service is running, its endpoint will be http://localhost:8080/v1/.

You don't need to set it for this demo application, as it has already been done here. So, for this demo application use case, once the backend service is running, you're ready to go to the next step.

Execute the backend-manager script. You can do so by opening up a terminal, navigating to this directory and running the following command:

./backend-manager start

To stop the backend:

./backend-manager stop

To stop the backend and remove the Docker image from your machine:

./backend-manager uninstall

Step 3: Launch the Android application

Open up this project with Android Studio and run the application in an Android Emulator. Once everything is running, navigate around in the app to generate some load that we would like to observe in Elastic APM. So, select a city, click Next and repeat it multiple times. To see the intentional error path, select New York in the Android app and tap Next. The backend rejects that city on purpose, which gives you an error trace to inspect and correlate with the Android-side request.

To demonstrate Android crash reporting, tap the floating crash button in the lower-right corner. The app will close intentionally. Tap Open app again, or launch it again from Android Studio or the emulator launcher, so the EDOT Android agent can export the buffered crash event.

Analyzing the data

After launching the app and navigating through it, open Kibana at http://localhost:5601 and log in with username elastic and the password printed at the end of the start-local setup. You can also find the password in elastic-start-local/.env (the ES_LOCAL_PASSWORD variable).

For a more detailed overview, take a look at how to Visualize telemetry in the docs.