Stacksaga Trace-Window Connector

Overview

Stacksaga Trace-Window Connector is the tool that allows you to connect your orchestrator service with Trace-Window by exposing the necessary APIs and data formats as endpoints.

Features

  • Exposes APIs for Trace-Window to fetch trace data from the orchestrator service from any supported databases implementations.

  • It supports both Spring MVC and Spring WebFlux based orchestrator services, allowing for flexibility in the choice of web framework.

  • Provide the authentication and authorization mechanisms to ensure secure access to the trace data for the production environment and authentication free access for the development environment.

Adding the Connector Dependency

To use the Trace-Window feature, first add the matching connector dependency to your project’s pom.xml. Stacksaga ships one such dependency per web stack; add the one that matches your orchestrator service’s technology:

Both dependencies pull in stacksaga-trace-window-connector-api transitively, so that shared module never needs to be declared or configured directly — declaring the servlet or webflux dependency is all that’s required on the dependency side. The dependency alone doesn’t switch the feature on, though: it must also be enabled via the stacksaga.trace-window.enable-api property, described in Configuration Properties.

stacksaga-trace-window-connector-servlet for Spring MVC Orchestrator Services

To enable Trace-Window for a Spring MVC based orchestrator service, add the stacksaga-trace-window-connector-servlet dependency to your project. This is what exposes the required APIs and data formats for Trace-Window to fetch trace data from your orchestrator service.

Here is an example of how to add the stacksaga-trace-window-connector-servlet dependency to your project

<dependencyManagement>
    <dependencies>
        <dependency> <!--Only for stacksaga dependencies version management-->
            <groupId>org.stacksaga</groupId>
            <artifactId>stacksaga-bom</artifactId>
            <version1.0.0-SNAPSHOT</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependencies>
    <dependency> (1)
        <groupId>org.stacksaga</groupId>
        <artifactId>stacksaga-trace-window-connector-servlet</artifactId>
    </dependency>
</dependencies>
1 Add the stacksaga-trace-window-connector-servlet dependency to enable Trace-Window for Spring MVC. This is the only Trace-Window connector dependency you need to declare — stacksaga-trace-window-connector-api comes along transitively.

stacksaga-trace-window-connector-webflux for Spring WebFlux Orchestrator Services

To enable Trace-Window for a Spring WebFlux based orchestrator service, add the stacksaga-trace-window-connector-webflux dependency to your project. This is what exposes the required APIs and data formats for Trace-Window to fetch trace data from your orchestrator service.

Here is an example of how to add the stacksaga-trace-window-connector-webflux dependency to your project.

<dependencyManagement>
    <dependencies>
        <dependency> <!--Only for stacksaga dependencies version management-->
            <groupId>org.stacksaga</groupId>
            <artifactId>stacksaga-bom</artifactId>
            <version1.0.0-SNAPSHOT</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependencies>
    <dependency> (1)
        <groupId>org.stacksaga</groupId>
        <artifactId>stacksaga-trace-window-connector-webflux</artifactId>
    </dependency>
</dependencies>
1 Add the stacksaga-trace-window-connector-webflux dependency to enable Trace-Window for Spring WebFlux. This is the only Trace-Window connector dependency you need to declare — stacksaga-trace-window-connector-api comes along transitively.

Configuration Properties

All properties are prefixed with stacksaga.trace-window.

Property Data Type Default Value Description

stacksaga.trace-window.enable-api

boolean

false

Enables the local /stacksaga API so that the Trace Window UI can connect to this service. Must be set to true for any of the other properties to have effect. When false the connector registers no filters or routes.

stacksaga.trace-window.secure-api

boolean

true

Protects every /stacksaga/* request with token-based authentication. When true (the default) the access-token property must also be provided. Set to false only in development or testing environments where unauthenticated CORS access is acceptable.

stacksaga.trace-window.access-token

String

(none)

The access token used to validate incoming /stacksaga requests. Required when both enable-api and secure-api are true. Generate this value from the StackSaga Trace Window UI and paste it here.

stacksaga.trace-window.connector-port

int

0 (disabled)

The port on which the /stacksaga connector port endpoints are exclusively exposed. When set, a secondary server connector is started on this port and any /stacksaga request arriving on the main application port is rejected with 403 Forbidden. Leave unset (or 0) to serve /stacksaga on the main application port.

Servlet: adds an extra Tomcat connector sharing the same thread pool — no extra threads are pre-allocated.
WebFlux: starts a separate Netty server with a minimal event loop — see connector-event-loop-threads below.

stacksaga.trace-window.connector-event-loop-threads

int

1

(WebFlux only) Number of Netty event-loop threads allocated to the secondary admin server started on connector-port. The default of 1 is intentionally minimal — Netty’s default would allocate CPU × 2 threads per server instance, which is wasteful for a rarely-accessed connector port. Raise this value only if the connector port receives sustained concurrent traffic. Must be at least 1. Has no effect in the Servlet variant.

stacksaga.trace-window.connector-ssl-bundle

String

(none)

The name of a Spring Boot SSL bundle (declared under spring.ssl.bundle.*) to use for HTTPS on the connector port. Only takes effect when connector-port is also set. The main application port’s SSL configuration is completely independent and is not affected. Leave unset to run the connector port over plain HTTP.
When enable-api=true and secure-api=true, startup validation enforces that access-token is present. The application will fail to start if the token is missing.

Configuration Examples

Minimal — API enabled with No authentication (Development / testing only)

stacksaga:
  trace-window:
    enable-api: true
    secure-api: false

Dedicated connector port (HTTP) and token authentication

  • The /stacksaga endpoints are only reachable on port 8787. Requests to /stacksaga on the main port receive 403 Forbidden.

  • Create access token. read more User management

stacksaga:
  trace-window:
    enable-api: true
    connector-port: 8787
    access-token: "your-token-generated-from-trace-window-ui"

Dedicated connector port with HTTPS (SSL bundle)

Define the SSL bundle under spring.ssl.bundle.* and reference it by name.

spring:
  ssl:
    bundle:
      jks:
        my-admin-cert:
          keystore:
            location: classpath:admin-keystore.p12
            password: changeit
            type: PKCS12

stacksaga:
  trace-window:
    enable-api: true
    access-token: "your-token-generated-from-trace-window-ui"
    connector-port: 8787
    connector-ssl-bundle: my-admin-cert
The main application port (e.g. server.port=8443) and the connector port can use different certificates. Each connector/server owns its SSL settings independently.

Dedicated connector port with custom thread count (WebFlux only)

Increase the event-loop thread count when the connector port is expected to handle sustained concurrent traffic.

stacksaga:
  trace-window:
    enable-api: true
    access-token: "your-token-generated-from-trace-window-ui"
    connector-port: 8787
    connector-event-loop-threads: 2
The connector-event-loop-threads property is only meaningful for the WebFlux variant. It has no effect in the Servlet variant.

Development / testing — no authentication (CORS only)

stacksaga:
  trace-window:
    enable-api: true
    secure-api: false
With secure-api=false the /stacksaga endpoints are accessible without any token. Do not use this setting in production.