Configuration Guide

1. Overview

FT System Metrics is configured through the following sources:

Source Description

application.yml

Main Spring Boot configuration with profiles for MySQL and Oracle

Environment Variables

Override parameters via environment variables (.env file or Docker environment)

prometheus.yml

Prometheus scrape target configuration

Docker Compose

Service stack configuration (ports, volumes, health checks)

2. Application YAML

The file src/main/resources/application.yml uses multi-document YAML with Spring profile groups.

2.1. Global Settings

spring:
  application:
    name: ft-system-metrics
  threads:
    virtual:
      enabled: true      # Java 25 virtual threads

server:
  port: ${SERVER_PORT:8080}
Property Default Description

spring.application.name

ft-system-metrics

Application name, used in metric tags

spring.threads.virtual.enabled

true

Enables Java 25 virtual threads for better concurrency

server.port

8080

Application HTTP port (default 8080; in Docker the host port is mapped to 8090 via HOST_PORT to avoid conflict with ACS)

2.2. Actuator & Metrics Settings

management:
  endpoints:
    web:
      exposure:
        include: health,info,prometheus,metrics
  endpoint:
    health:
      show-details: always
  metrics:
    tags:
      application: ${spring.application.name}
    distribution:
      percentiles-histogram:
        http.server.requests: true
      sla:
        http.server.requests: 10ms, 50ms, 100ms, 200ms, 500ms
Property Default Description

management.endpoints.web.exposure.include

health,info,prometheus,metrics

Exposed Actuator endpoints

management.endpoint.health.show-details

always

Show detailed health check information (including database status)

management.metrics.tags.application

ft-system-metrics

Global application tag applied to all metrics

management.metrics.distribution.percentiles-histogram

true for http.server.requests

HTTP request percentile histogram

management.metrics.distribution.sla

10ms, 50ms, 100ms, 200ms, 500ms

SLA buckets for HTTP request duration distribution

2.3. Common JPA Settings (profile: common)

spring:
  jpa:
    hibernate:
      ddl-auto: none                  # Read-only, no schema modifications
    show-sql: ${JPA_SHOW_SQL:false}
    open-in-view: false
    properties:
      hibernate:
        format_sql: true
        jdbc:
          time_zone: UTC
        jdbc.lob:
          non_contextual_creation: true
        jakarta:
          persistence:
            validation:
              mode: none
Property Default Description

hibernate.ddl-auto

none

Do not modify the database schema — the service operates in read-only mode

JPA_SHOW_SQL

false

SQL query logging (enable for debugging)

open-in-view

false

Disables the Open Session in View anti-pattern

hibernate.jdbc.time_zone

UTC

Timezone for all database operations

validation.mode

none

Disables JPA validation (service only reads data)

3. Environment Variables

3.1. Application Configuration

Variable Default Description

HOST_PORT

8090

Host port for Docker port mapping (container always listens on 8080; 8090 avoids conflict with ACS)

DB_VENDOR

mysql

Database selection: mysql or oracle. Determines the active Spring profile

JAVA_OPTS

-Xms256m -Xmx512m

JVM parameters

TZ

UTC

Container timezone

JPA_SHOW_SQL

false

SQL query logging

LOG_PATH

logs

Directory for application log files (see Logging)

3.2. Database Configuration (Common)

Variable Default Description

DB_HOST

localhost

FTACS database host

DB_PASSWORD

ftacs

Database connection password

DB_MAX_POOL

10

Maximum HikariCP connection pool size

DB_MIN_POOL

2

Minimum number of idle connections in the pool

3.3. MySQL-Specific Variables

Variable Default Description

MYSQL_PORT

3306

MySQL server port

MYSQL_USER

ftacs

MySQL username

MYSQL_SCHEMA

ftacs

MySQL database (schema) name

MYSQL_URL

auto-generated

Full JDBC URL (overrides individual parameters)

3.4. Oracle-Specific Variables

Variable Default Description

ORACLE_PORT

1521

Oracle listener port

ORACLE_USER

ftacs

Oracle username

ORACLE_SERVICE

orclpdb1

Oracle service name

ORACLE_URL

auto-generated

Full JDBC URL (overrides individual parameters)

3.5. Monitoring Stack Variables

Variable Default Description

PROMETHEUS_PORT

9090

External Prometheus port (Docker Compose)

GRAFANA_PORT

3000

External Grafana port (Docker Compose)

GRAFANA_PASSWORD

admin

Grafana admin password

DATA_FOLDER

. (current directory)

Root folder for persistent data (Prometheus, Grafana)

4. Spring Profiles

The application uses profile groups to organize configuration:

spring:
  profiles:
    group:
      mysql:  [ common, mysql ]
      oracle: [ common, oracle ]
Profile Contents

common

JPA settings (ddl-auto, format_sql, timezone), HikariCP pool configuration, validation mode

mysql

MySQL JDBC driver, connection URL, MySQLDialect, MySQL-specific HikariCP settings (rewriteBatchedStatements, connectionTimeZone)

oracle

Oracle JDBC driver, connection URL, OracleDialect

5. HikariCP Connection Pool

Advanced connection pool parameters (profile: common):

Variable Default Description

DB_MAX_POOL

10

Maximum pool size

DB_MIN_POOL

2

Minimum idle connections

HIKARI_REGISTER_MBEANS

false

Register JMX MBeans for pool monitoring

HIKARI_IDLE_TIMEOUT_MS

60000

Maximum idle time for a connection (ms)

HIKARI_CONN_TIMEOUT_MS

45000

Timeout for obtaining a connection from the pool (ms)

HIKARI_MAX_LIFETIME_MS

180000

Maximum lifetime of a connection (ms)

HIKARI_VALIDATION_TIMEOUT_MS

3000

Connection validation timeout (ms)

JDBC_CACHE_PREP_STMTS

true

Prepared statement caching

JDBC_PREP_STMT_CACHE_SIZE

512

Prepared statement cache size

JDBC_PREP_STMT_SQL_LIMIT

2048

Maximum SQL length for caching

JDBC_USE_SERVER_PREP_STMTS

false

Use server-side prepared statements

6. Logging

The application uses Logback with a Spring Boot integration (logback-spring.xml).

6.1. Console Output

Console logging is always active and uses the default Spring Boot format.

6.2. File Output

File logging is enabled for profiles local, mysql, oracle, and test. Log files are written to the path defined by LOG_PATH (defaults to logs/ relative to the working directory — /app/logs inside the Docker container).

Variable Default Description

LOG_PATH

logs

Directory for log files (inside the container: /app/logs)

Rotation policy:

Parameter Value

Rotation

Daily (application.YYYY-MM-DD.log.gz)

Retention

30 days

6.3. Accessing Logs on the Host

The compose.yml mounts the container log directory to the host:

volumes:
  - ./logs:/app/logs

After the container starts, log files are available in the logs/ directory next to the compose file.

7. Prometheus Configuration

The prometheus.yml file in the project root:

global:
  scrape_interval: 15s
  evaluation_interval: 15s

scrape_configs:
  - job_name: 'spring-boot-app'
    metrics_path: '/actuator/prometheus'
    static_configs:
      - targets: ['ft-system-metrics:8080']
Parameter Default Description

scrape_interval

15s

Metrics polling frequency

evaluation_interval

15s

Recording/alerting rule evaluation frequency

metrics_path

/actuator/prometheus

Metrics endpoint path

targets

ft-system-metrics:8080

Application address (Docker Compose service name and container port)

When running via docker run (without Compose), replace the target with host.docker.internal:8090 or the host IP address (use the host port, not the container port).