Using OpenSearch as the traces storage for Tracetest

Tue, Sep 27, 2022 · Matheus Nogueira

I am excited to announce that Tracetest now supports OpenSearch! If you already use OpenSearch Trace Analytics, you can start writing tests based on your telemetry using Tracetest without having to change anything in your application. In this article, we will explain how you can start building trace-based tests right now.

What is Tracetest?

Tracetest is an open-source project that allows you to use your telemetry data to assert the behavior of your application. It fetches the telemetry generated by your application during a test execution and uses it to run assertions against it. With this functionality, you can verify if the latencies of your system are within your thresholds, validate your application flow and much more. It is also quite useful for writing end-to-end tests when you don’t have a complete understanding of how the application interacts with other services. You can use the trace generated by a test to do exploration work while writing your tests.

Installing Tracetest with OpenSearch

The Tracetest team is working diligently to make installation as seamless as possible. Currently, you can use CLI to install the server to run on either Docker Compose or Kubernetes. Visit the installation guide to install both the CLI and server.

Before proceeding, make sure you have an OpenSearch instance running and have a Data Prepper instance pointing to it. Data Prepper is an OpenSearch component capable of converting OpenTelemetry format into JSON that can be indexed by OpenSearch. Tracetest has an example application. See how Data Prepper is configured.

For simplicity’s sake in this article, you will learn how to setup Tracetest using Docker Compose. Execute the following steps to configure your Tracetest instance to connect to your OpenSearch instance:

  1. Run tracetest version to verify your CLI version.
    1. Check if your CLI version is greater or equal to 0.7.2.
  2. Create a folder called tracetest-demo.
     mkdir ~/tracetest-demo
    
  3. Open the folder on your terminal.
     cd ~/tracetest-demo
    
  4. Run tracetest server install and follow the steps:
    1. Select Using Docker Compose.
    2. Allow the CLI to install any dependency that might be missing from your system.
    3. Project’s docker-compose file? Press Enter
    4. Do you want me to create an empty docker-compose file? Yes
    5. Do you have a supported tracing backend you want to use? (Jaeger, Tempo, OpenSearch, SignalFX) Yes
    6. Select OpenSearch
    7. Set the addresses to match your nodes’ addresses
      • Consider that the collector is running inside a Docker container, so you cannot use localhost to reference other containers running on your machine. Use either host.docker.internal (Mac) or 172.17.0.1 (Linux) to reference your local machine.
    8. Set the index used to store your traces.
    9. Set your data-prepper endpoint.
      • Consider that the collector is running inside a Docker container, so you cannot use localhost to reference other containers running on your machine. Use either host.docker.internal (Mac) or 172.17.0.1 (Linux) to reference your local machine.
    10. Do you have an OpenTelemetry Collector? No
    11. Do you want me to set up one? Yes
    12. Do you want to enable the demo app? Yes
    13. Tracetest output directory Press Enter
  5. Run the docker compose command that the CLI just printed on your terminal:
     docker compose -f docker-compose.yaml -f tracetest/docker-compose.yaml up -d
    

Now you should have Tracetest running and connected to your OpenSearch instance.

Creating Your First Test

You should be able to access Tracetest by opening http://localhost:8080 on your browser and see Tracetest’s home screen:

Tracetest home page

Click on Create Test, select HTTP Request and then click on Next.

Tracetest create http test

Click on Choose Example, select Pokemon - Add, and then click on Next.

Tracetest create http test

To review the request that is used to trigger the test, you don’t have to change anything. Just click on Create.

Now you can see the result of the test execution. You should be seeing the response from the Pokemon demo:

Tracetest test trigger details

Click on Trace to see the trace generated by the Pokemon demo when the test was executed. This trace was retrieved from your OpenSearch instance!

Tracetest test trace

And, if you click on Test, you will see all assertions for this test. However, as you just created the test, there aren’t any assertions yet. You can add one to see how it works. Click on the POST /pokemon span and then click on Add Test Spec.

Empty assertions

This will generate the query to select that specific span in the trace. Then you can add assertions based on attributes from that span. Next, test executions will run those assertions against the new trace automatically. To show its capabilities, add two assertions to that span.

Select http.status_code Equals 201 to assert that the status code of the request will be 201 everytime this test is run. Select tracetest.span.duration Less than 100ms and to assert that the request will take less than 100ms to run in future tests.

Empty assertions

Click on Save Test Spec and then on Publish.

Now it’s possible to run the test. Tracetest will execute all assertions you just created using the new trace. Click on Run Test and wait for the test to finish executing.

Adding assertions

Tracetest is not only a UI tool. You also can run that test from your CI environment. Click on the gear icon at the top of the page and click on Test Definition.

Export test definition Exported definition

Copy the test definition and save into a file. Then open your terminal, and type tracetest test run -d your-file.yaml -w and wait for the result.

CLI Test result

Conclusion

With this new integration, any team using OpenSearch as your OpenTelemetry trace data store will be able to use Tracetest to help you test your application. We are super excited to work with the OpenSearch community to release the integration and to continue to enhance this feature as we develop Tracetest. If you have any issues or questions about Tracetest with OpenSearch, reach out the team on the Discord channel or open an issue on the git repository.