From ERP to CZZ

Integration platform for connecting external ERP systems with comerzzia.

Overview

The ERP to CZZ integration consists of two main components:

Architecture

The integration follows a message-driven architecture where data flows from external ERP systems through the Input layer, which validates and publishes messages to a message broker (Kafka or Pub/Sub), and then the Processor layer consumes these messages to update the comerzzia database.

Technologies

  • Java 8+

  • Spring Boot 2.7.18

  • Apache Kafka / Google Cloud Pub/Sub

  • Maven 3.6+

Observability / health check

  • Spring Boot Actuator

    • Health checks, metrics, and application info endpoints

    • Prometheus metrics export via /actuator/prometheus

  • Monitor-UI embedded

    • JSON metrics available via /monitor/metrics

Business Metrics (Prometheus)

Micrometer converts . to _ and appends _total to counters. Names below are the exact Prometheus metric names. For counters, use rate(metric[5m]) or increase(metric[5m]) in PromQL, not the raw value.

Global Counters — type: counter

Prometheus metric Description Incremented by

messages_received_total

Messages received for processing

REST API / Folder: on message received

messages_processed_total

Messages processed successfully

REST API / Folder: on success

messages_failed_total

Messages failed

REST API / Folder: on error

messages_sent_to_error_topic_total

Messages sent to error topic

Processor: on DLQ send

messages_retried_total

Total retries performed

Processor: on retry result

retry_success_total

Retries that eventually succeeded

Processor: retry success

retry_failure_total

Retries that failed again

Processor: retry failure

retry_scheduled_total

Retries republished to main topic

Processor: before republish

messages_retried_total, retry_* and messages_sent_to_error_topic_total are defined but not currently incremented in the REST API or Folder implementations — only in Kafka/Pub/Sub processor applications if retry logic is active.

Per-Entity Counters — type: counter

Prometheus metric Labels Description Incremented by

entity_messages_received_total

entity

Messages received per entity

REST API / Folder: on message received

entity_messages_processed_total

entity, result (success/failure)

Messages processed per entity and result

REST API / Folder

errors_by_type_total

error_type

Errors grouped by exception class name

Processor: on DLQ send

Folder-specific Gauges — type: gauge — label: entity (folder application only)

Prometheus metric Description

folder_files_pending

Number of files pending processing in input folder

folder_files_processed

Number of files in processed folder

folder_files_failed

Number of files in failed folder

Processing Time — type: histogram

Prometheus metric Description

entity_processing_time_seconds_count

Number of observations

entity_processing_time_seconds_sum

Total accumulated time (seconds)

entity_processing_time_seconds_max

Max time recorded in current interval

entity_processing_time_seconds\{quantile="0.5"}

p50 (median)

entity_processing_time_seconds\{quantile="0.95"}

p95

Average processing time per entity (PromQL):

rate(entity_processing_time_seconds_sum[5m]) / rate(entity_processing_time_seconds_count[5m])