Skip to main content
Version: 26.1

Asynchronous reporting

Overview​

Asynchronous reporting is set up using the AMQP 0-9-1 protocol with RabbitMq as the message broker. The main idea is to respond to the client immediately after the server receives a request. This way, the client isn't blocked and doesn't have to wait for the server to process the request. Additionally, it acts as a requests load balancer, storing it in queues until the backend is free to process them.

Scheme of interactions between RabbitMq and API​

Difference between ID and UUID

ID is a numerical identifier for an entity, automatically generated by the database at the moment of saving. UUID is a string virtual identifier for an entity. UUID can be generated on the client side and provided with a request. If it is not provided, it is generated automatically when the API accepts the request. Each entity has both ID and UUID. ID is used to perform the CRUD operations on an entity that is already saved in db. UUID is used to build the child-parent relationships between entities on the client side during reporting. In case of synchronous reporting, any response from API is returned after the request is handled and the entity is saved in the database. In case of asynchronous reporting, any response from API is returned before the request is handled and the entity is saved in the database and after the request is published to the queue. The responses in both modes look the same:

{
"id": "cd64d5eb-fea1-4e7e-8a5a-69998ac5620f"
}

The id property in the response is actually an UUID. This is for backward compatibility. Therefore, when you have this UUID and want to update or delete the entity, you need to first retrieve the physical ID. It can be done via API:

Asynchronous reporting scheme

  • Step 1
    API receives HTTP request from client to the reporting controller. The Controller verifies permissions and call the producer logic.
  • Step 2
    Producer validates business rules if necessary, generates UUID (virtual id) if it is not provided in request, builds a message for RabbitMq and sends it to the exchange with x-consistent-hash type. After message is sent, the controller returns HTTP response to the client with UUID. At the moment, the physical entity in database may not be created yet!
  • Step 3
    Consumer starts processing the message as soon as it is received from RabbitMq. After a successful processing, the entity will be stored in a database and obtain a physical id. If a retryable “not found” exception occurs, the message is delayed in a retry TTL queue and requeued. Other failures go to the parking lot; the entity is not saved.

Enable asynchronous reporting in agents​

Async reporting is supported only by agents since version 5.0.0. To enable it you should set rp.reporting.async=true in reportportal.properties. By default (if property rp.reporting.async is not specified) agents work in a synchronous mode.

rp.endpoint=https://example.com
rp.api.key=xxx
rp.launch=launch-name
rp.project=project-key
rp.reporting.async=true

(*) Listed above is an example for Java-based client. For another platforms please see corresponding documentation.

important

Starting from ReportPortal 26.1, reporting API endpoints use project key (projectKey) instead of project name.

You can find the project key in Project settings → General.

Asynchronous API​

Async controllers have /api/v2 prefix. Requests and responses have no differences with sync ones but there are some specific distinctions in the behavior that is described in reporting guide.

Detailed scheme of interactions between RabbitMq and API​

API properties​

API has the following properties for connection to RabbitMq service:

NameEnvironment variable nameDefault value
rp.amqp.hostRP_AMQP_HOSTrabbitmq
rp.amqp.portRP_AMQP_PORT5672
rp.amqp.userRP_AMQP_USERempty (must be set)
rp.amqp.passRP_AMQP_PASSempty (must be set)
rp.amqp.addressesRP_AMQP_ADDRESSESamqp://${rp.amqp.user}:${rp.amqp.pass}@${rp.amqp.host}:${rp.amqp.port}
reporting.queues.countREPORTING_QUEUES_COUNT10
reporting.retry.max-countREPORTING_RETRY_MAX_COUNT20
reporting.parkingLot.ttl.daysREPORTING_PARKINGLOT_TTL_DAYS7

rp.amqp.host - Hostname of RabbitMq service.
rp.amqp.port - Port of RabbitMq service.
rp.amqp.user - Username to connect to RabbitMq service.
rp.amqp.pass - User password to connect to RabbitMq service.
rp.amqp.addresses - Full address to connect to RabbitMq service.
reporting.queues.count - Number of reporting queues created and consumed by this service-api instance.
reporting.retry.max-count - Maximum number of retries before a message is moved to the parking lot.
reporting.parkingLot.ttl.days - How long messages are kept in the parking lot for manual analysis.

Exchanges and queues for reporting​

The API creates two exchanges: e.reporting and e.reporting.retry.

  • e.reporting is an x-consistent-hash exchange. It routes reporting messages to per-instance queues.
  • e.reporting.retry is a direct exchange used for delayed retries of failed messages.

The number of main reporting queues depends on reporting.queues.count (REPORTING_QUEUES_COUNT).
Each service-api instance declares its own queues named q.reporting.{instanceId}.0 … q.reporting.{instanceId}.{N-1}, where {instanceId} is preferably the pod/hostname (HOSTNAME), otherwise a short random id. This lets an instance reclaim its queues after restart.

Retry uses three TTL queues bound to e.reporting.retry (messages dead-letter back to e.reporting):

QueueTTLUsed when retry count is
q.retry.reporting.ttl.ms500 ms0–5
q.retry.reporting.ttl.s5 s6–10
q.retry.reporting.ttl.m2 min11 and higher (until max retry count)

If a message exceeds reporting.retry.max-count (default 20), it is moved to q.parkingLot.reporting, where it is stored for reporting.parkingLot.ttl.days (default 7 days) for manual error analysis.

Scheme​

All requests (items, logs) related to the same launch will be stored in the same RabbitMQ queue. This is achieved by using an exchange that maps messages to queues using the Consistent Hashing algorithm (hash header hash-on, typically the launch UUID).

Messages in the queue don't have a strict order but they are stored mostly in the same order as they arrive from client. This ensures a minimal amount of exceptions (causing the sending of such messages to the retry queues) caused by cases when a child is handled before its own parent.

Consuming scheme:

(!) Only retryable “entity not found” errors are sent to the retry TTL queues. Any other exception is moved directly to q.parkingLot.reporting for manual analysis.

Retryable cases (default after retries are exhausted → parking lot):

  • On start launch/test item:
    • Entity not found. Parent entity not found.
  • On finish launch/test item:
    • Entity not found. Entity that has to be finished not found in database or parent entity not found (for test items).
  • On log creation:
    • Entity not found. Trying to create log for not existing launch/test item

Finishing launch​

If the order is not broken, launch finish request will be handled when there are no more child item requests in the queue.

(!) It is a main difference in reporting mechanism between ReportPortal version 4 and 5. If the launch finish request is not the last in the queue, the launch will be finished anyway. However, all subsequent requests related to that launch will be handled as they reach the consumer, and the launch statistics will be updated accordingly. This means it is possible to report items under an already finished launch. Events associated with the launch finish will be processed as soon as the launch finish is handled. Items processed after the launch finish will not be included in post-launch handling processes such as 'Auto Analysis' and 'Quality Gates.'