Architecture

This page aims to provide an overview of Mtracer’s architecture and its internal workings.

Container diagram

Mtracer offers two main commands: mtracer create and mtracer run, which allow you to create tests and execute them, respectively.

mtracer create is a command that allows you to generate a new test file with the .mt.yaml extension inside the specified directory, providing a basic structure that can be modified according to the developer’s needs. It is a support command that is not strictly necessary to create a test file, but it is recommended to avoid syntax errors and speed up the creation process.

mtracer run is the command that executes the tests passed as arguments or, in the absence of arguments, all the tests present in the current working directory. This command represents the core of Mtracer, as it allows you to execute tests and verify that the traces generated by the tested system conform to the expected ones, as defined in the test files. Furthermore, it is the only command that interacts with the outside, interfacing with the following systems:

• Observability backend: collects and stores the traces generated by the system. Mtracer interfaces with it to retrieve the traces related to the execution of the tests and compare them with the expected ones.
• System under test: is the tested application. Mtracer interacts with it through an initial request called a trigger, whose purpose is to generate a trace within the system itself.

Component diagram

In this section, you can view a more detailed diagram of the mtracer run command, including its internal components and their interactions.

Run Test Controller

It is the component responsible for receiving the command from the CLI, interpreting and validating the passed parameters and the current configuration. Furthermore, it orchestrates the parsing of the test files and the execution of the tests themselves, interfacing with the Test Parser and the Test Runner.

Parser

It is responsible for reading and interpreting the test files, converting their structure from YAML format to an internal data structure that can be used by the Run Test Controller for execution.

Validator

It has the task of verifying that the internal data structure and the fields generated by the Parser are valid and conform to expectations. It also provides to insert default values in the missing fields (where possible) and to report any validation errors to the Run Test Controller.

Trace Test Runner

It is the orchestrator of the single test: it manages all the phases necessary for its execution. It interfaces with the Setup Command Executor, Trigger Invoker, Trace Fetcher, Trace Comparator, Asserter and Cleanup Command Executor components. It also has the task of returning the test result to the Run Test Controller.

Setup Command Executor

Executes the setup commands necessary before test execution. Setup commands are optional, they can be defined within the test files and serve to prepare the environment before the trigger invocation (for example, to start a Docker container required by the test). To learn more about setup commands and their configuration, see the Setup commands page.

Trigger Invoker

Executes the trigger defined in the test file. The purpose is to generate a traceId and inject it into the tested system via a call to a service. In this way, the traceId will be propagated in the system, subsequently allowing the trace to be retrieved via the observability backend. The trigger can be of different types, depending on the developer’s needs and the system under test. The types of triggers supported by Mtracer are listed in the Triggers page.

Trace Fetcher

Interfaces with the observability backend to retrieve the trace generated by the system following the trigger execution. Mtracer supports several observability backends to meet the needs of various systems and developers. The supported backends are listed in the Observability backend configuration page.

Trace Comparator

Compares the characteristics of the retrieved trace with those of the expected trace (or sub-trace) defined in the test file. It returns a result that is as clear and explanatory as possible regarding any differences found.

Asserter

Executes the assertions and queries defined in the test file. Assertions are boolean expressions applied to the collected trace; in order for the test to be considered passed, all assertions must be true. They are designed to offer a higher level of flexibility and customization than simply defining an expected trace. The types of assertions supported by Mtracer can be found in the Assertions page.

Cleanup Command Executor

Executes the cleanup commands necessary at the end of the test. This type of command is optional and serves to clean the environment after the execution of the setup commands. Each type of setup command has a corresponding cleanup command, which can be mandatory to define or already present by default, depending on the setup used. This component is essential to allow the repeated execution of tests without the risk of compromising or “dirtying” the tested system.

Post Exec Checker

At the end of the test execution, this component has the task of executing assertions within the tested system. These assertions are optional and serve to verify that the system has remained in a consistent state or has entered the correct state after the test execution. You can learn more about the details of the post exec checkers in the Post execution controls page.

Results Exporter

It is responsible for exporting the test results in various formats, such as JSON, Markdown or JUnit. This feature allows test results to be exported in standardized formats, facilitating integration with other tools or data analysis pipelines.

Analytics Exporter

It has the task of exporting the statistics of the traces and spans generated by the executed tests, allowing developers to obtain a comprehensive overview of the performance of the system under test and highlighting any variations or anomalies in the results. You can learn more about the feature in the Statistics export page.