Mtracer Examples

This repository contains ready-to-run examples demonstrating how to use Mtracer—a CLI tool for system testing powered by OpenTelemetry trace validation.

The examples show how to configure Mtracer to verify traces generated across distributed architectures (using HTTP, gRPC, and NATS) and check system side-effects.

---

Prerequisites

Before running any examples, make sure you have the following installed on your system:

• Docker & Docker Compose: to spin up the distributed services and observability backends.
• Mtracer CLI: to run the tests. Follow the Mtracer Installation Guide to install the CLI on your machine.

---

Available Examples

rollDice

The rollDice project is a distributed microservice application designed to demonstrate how to use Mtracer for system trace validation. It consists of multiple services communicating via HTTP, gRPC, and NATS, with traces collected by Jaeger or OpenObserve. The application simulates a dice rolling system where users can roll dice, and the results are processed and verified across different services.

Architecture Components:

• Target Services:
  • diceFrontend: Web app sending rolling requests.
  • dice: Dice service generating numbers.
  • grpcServer: Roll coordinator communicating via gRPC.
  • evenOrOdd: Service verifying number parity.
  • natsConsumerAndServer: Processing queue messages via NATS.
• Observability Backends: Jaeger and OpenObserve to collect trace spans.
• Database: PostgreSQL to persist transaction rolls.

---

How to Run the Examples

To run the rollDice example:

1. Navigate to the example directory:

   cd rollDice

2. Start the microservices: Run the startup script to download, build, and run the application services, databases, and Jaeger/OpenObserve in the background:

   ./start.sh

   Note: Ensure Docker is running on your system.

3. Configure Mtracer: Mtracer needs to know where your observability backend is. By default, the examples use jaeger or openobserve containers defined in docker-compose.yml. You can configure your local settings by creating a .env file or passing variables (see Mtracer Configuration).

4. Execute the Trace Tests: Run the pre-configured YAML test suites using Mtracer:

   mtracer run

   This will execute the triggers, wait for traces to be generated, fetch them from the backend, and assert that the structure, spans, and database entries match the expected outputs.

5. Stop and Clean Up: Once you are done testing, tear down the containers and clean up Docker volumes using:

   ./stop.sh