DEV Community: Abhishek Dhiman

Building a Multi-Tenant QuickBooks Integration with Spring Boot and Nango

Abhishek Dhiman — Thu, 08 Oct 2026 14:06:24 +0000

I wanted to see how much of the integration work Nango could handle from a Java/Spring Boot application, so I built a small multi-tenant accounting backend using Java, Spring Boot, Nango, and QuickBooks Online Sandbox. A customer can connect their QuickBooks account, and the backend can then fetch their company information, customers, and invoices. I also tested the integration with a real QuickBooks Sandbox instead of relying only on mocked responses.

And I also wanted to see what the Java experience would look like. The Nango Java backend SDK documentation currently points developers to the REST API while the SDK is still marked as coming soon, so I built a small Java client using Spring's RestClient.

While building it, I ran into a few things I hadn't expected, like the end_user requirement for Connect Sessions, the QuickBooks OAuth scope, handling the realmId, Nango errors, and webhooks. In this article, I'll walk through what I built and what I learned along the way.

GitHub: https://github.com/abhishek-dhnma/nango-java-quickbooks-integration-demo

1. Prerequisites

Before starting, you'll need:

Java 17+
Spring Boot 3.3.4
Maven
A Nango Cloud account
An Intuit Developer account
A QuickBooks Online Sandbox company

The QuickBooks Sandbox lets us go through the real OAuth flow and make API requests without using a production QuickBooks account.

Once these are ready, we can start with the QuickBooks setup.

2. Create a QuickBooks Developer App

First, create an application in the Intuit Developer portal. This gives us the OAuth credentials and permissions that Nango will use when connecting to QuickBooks.

From Sign In > My Hub > App dashboard, create a new app and select QuickBooks Online and Payments.

For this project, I used the com.intuit.quickbooks.accounting scope because the backend needs access to accounting data such as company information, customers, and invoices.

Once the app is created, open Keys & credentials > Development and copy the Client ID and Client Secret. We'll configure these credentials in Nango in the next section.

We're using Development credentials because the project connects to a QuickBooks Sandbox rather than a production company.

3. Create a QuickBooks Sandbox Company

Next, create a QuickBooks Online Sandbox company from the Intuit Developer portal. The Sandbox gives us a test company that we can use for the OAuth flow and API requests without connecting a production QuickBooks account.

If you already have a Sandbox company, you can skip this step.

We also need the QuickBooks realmId, which identifies the connected company. In the Sandbox, you can find it under Settings > Profile > Subscription and Billing > Company ID. The Company ID is the realmId used by the QuickBooks API.

Note: Nango can retrieve the realmId automatically during the connection flow, so it can also be left blank when configuring the Sandbox connection in Nango. I used the value returned in the Nango connection metadata when building the Spring Boot integration.

Once the Sandbox is ready, we can configure the QuickBooks integration in Nango.

4. Configure QuickBooks in Nango

Nango already provides a QuickBooks Sandbox integration, so we can configure it without implementing the provider OAuth flow ourselves.

In Nango, open the QuickBooks Sandbox integration and add the Client ID and Client Secret from the Intuit Developer app. Use quickbooks-sandbox as the provider configuration key and the com.intuit.quickbooks.accounting scope for this project.

Nango also provides an OAuth callback URL. Copy it into the Redirect URIs section of the Intuit Developer app under Keys & credentials > Development.

At this point, the Nango provider configuration is ready. We won't create a separate test connection from the Nango dashboard; the actual QuickBooks connection will be created later through the Connect Session from Spring Boot.

Next, we'll start the Spring Boot application and create a Nango Connect Session for a tenant.

5. Create a Nango Connect Session from Spring Boot

With the QuickBooks integration configured in Nango, clone the project from GitHub and open the project directory.

Create a .env file from .env.example and add your Nango credentials:

NANGO_BASE_URL=https://api.nango.dev
NANGO_SECRET_KEY=your_nango_secret_key
NANGO_INTEGRATION_KEY=quickbooks-sandbox
NANGO_WEBHOOK_SIGNING_KEY=your_nango_webhook_signing_key

In Nango, Environment settings > API keys and copy the Secret Key for your environment. Add it to .env as NANGO_SECRET_KEY.

Then start the application:

.\run.ps1

Once the application is running, create a Connect Session for the tenant:

curl -X POST \
  http://localhost:8080/api/tenants/tenant-1/accounting/connect

Note 1: The tenant-1 value in the URL is an application-level tenant ID. It isn't generated by Nango. For this demo, tenant-1 is a sample tenant defined by the application and used to identify the customer whose QuickBooks account we're connecting. In a real application, this ID would normally come from the authenticated user's or organization's context rather than being hardcoded in the URL.

Note 2: Windows PowerShell: If curl is mapped to Invoke-WebRequest on your system, use curl.exe instead.

One small addition I'd make

The project also includes a small frontend called LedgerFlow that uses these Spring Boot endpoints to display the connected QuickBooks company, customers, and invoices. It provides a simple tenant selector and QuickBooks connection flow, so the backend integration can also be shown through a UI.

The endpoint creates a Nango Connect Session and returns a connect_link that the tenant can open to start the QuickBooks authorization flow. The controller passes the tenant ID to the accounting service, which creates the Connect Session:

public NangoConnectSessionResponse initiateAccountingConnection(
        String tenantId) {

    NangoEndUser endUser = new NangoEndUser(tenantId);

    Map<String, String> tags = Map.of(
            "organization_id", tenantId
    );

    return nangoClient.createConnectSession(
            List.of(integrationKey),
            endUser,
            tags
    );
}
}

The tenantId is passed to Nango as the end_user.id. I also send it as the organization_id tag. This tag is used later by the Nango auth webhook to associate the newly created Nango connection with the correct tenant.

The NangoClient keeps the Nango HTTP calls outside the controller and uses Spring's RestClient:

public NangoConnectSessionResponse createConnectSession(
        List<String> allowedIntegrations,
        NangoEndUser endUser,
        Map<String, String> tags) {

    NangoConnectSessionRequest request =
            new NangoConnectSessionRequest(
                    allowedIntegrations,
                    endUser,
                    tags,
                    null
            );

    return restClient.post()
            .uri("/connect/sessions")
            .contentType(MediaType.APPLICATION_JSON)
            .body(request)
            .retrieve()
            .body(NangoConnectSessionResponse.class);
}

The request sent to Nango now contains the allowed integration, the end user, and the tenant tag:

{
  "allowed_integrations": ["quickbooks-sandbox"],
  "end_user": {
    "id": "tenant-1"
  },
  "tags": {
    "organization_id": "tenant-1"
  }
}

Nango returns a Connect Session containing a connect_link:

{
  "data": {
    "token": "<redacted>",
    "connect_link": "https://connect.nango.dev/?session_token=<redacted>"
  }
}

One thing I discovered while building this was that end_user is required when creating the Connect Session. My initial request without it returned a 400 response, so I added the tenant ID as the end_user.id.

The Connect Session only starts the authorization flow. After the tenant completes QuickBooks authorization, Nango creates the actual connection and sends an auth webhook to the application. The webhook uses the organization_id tag to associate the new connection_id with the tenant.

6. Complete the QuickBooks OAuth Connection

The Connect Session response contains a connect_link. Copy this URL and open it in a browser to start the connection flow. Nango opens its Connect UI, where you can continue with the QuickBooks Sandbox authorization flow. Sign in to the Sandbox account and authorize the application.

After the authorization is completed, Nango creates the QuickBooks connection and shows a success screen.

At this point, the QuickBooks Sandbox account is connected through Nango. The application can use this connection to make authenticated QuickBooks API requests through the Nango Proxy.

One important detail is that the Connect Session only starts the authorization flow. After the tenant completes the QuickBooks authorization, Nango sends an auth webhook containing the new connection_id. The application uses the organization_id tag from the Connect Session to identify the tenant and stores the connection ID in TenantRepository. The demo uses an in-memory implementation, while a production application would normally persist this mapping in a database.

7. Resolve the Nango Connection and `realmId`

Once the QuickBooks connection has been created and mapped to the tenant, the application can resolve the Nango connection and retrieve the QuickBooks realmId.

The Spring Boot service first looks up the Nango connection_id for the tenant:

private String resolveConnectionId(String tenantId) {
    return tenantRepository.findConnectionId(tenantId)
            .orElseThrow(() ->
                    new IllegalStateException(
                            "No accounting connection found for tenant: "
                                    + tenantId));
}

Once the connection_id is resolved, the application asks Nango for the connection metadata and reads the QuickBooks realmId:

private String resolveRealmId(String connectionId) {
    return realmIdCache.computeIfAbsent(connectionId, connId -> {

        NangoConnection connection =
                nangoClient.getConnection(
                        connId,
                        integrationKey
                );

        if (connection.connectionConfig() != null
                && connection.connectionConfig().containsKey("realmId")) {

            return String.valueOf(
                    connection.connectionConfig().get("realmId")
            );
        }

        throw new IllegalStateException(
                "Nango connection " + connId
                        + " does not have a 'realmId' configured."
        );
    });
}
}

The important part is that the application does not hardcode the QuickBooks realmId. It resolves the tenant's Nango connection first, then reads the realmId from the connection metadata returned by Nango.
The resolved realmId is also kept in an in-memory cache, so the application does not need to retrieve the same connection metadata from Nango on every request.
With the tenant's Nango connection and QuickBooks realmId resolved, the application can now make its first QuickBooks API request through the Nango Proxy.

8. Making the First QuickBooks API Request

Now that the application can resolve the tenant's connection_id and realmId, it can make a request to QuickBooks through the Nango Proxy.

The application exposes:

GET /api/tenants/{tenantId}/accounting/company

For example:

curl http://localhost:8080/api/tenants/tenant-1/accounting/company

The service resolves the connection and realmId, then passes the QuickBooks request to the NangoClient:

public CompanyInfo getCompanyInfo(String tenantId) {

    String connectionId = resolveConnectionId(tenantId);
    String realmId = resolveRealmId(connectionId);

    return nangoClient.proxyGet(
            connectionId,
            integrationKey,
            "/v3/company/" + realmId
                    + "/companyinfo/" + realmId
    );
}

The NangoClient makes the actual request to the Nango Proxy:

public CompanyInfo proxyGet(
        String connectionId,
        String providerConfigKey,
        String path) {

    return restClient.get()
            .uri(uriBuilder -> uriBuilder
                    .path("/proxy" + path)
                    .build())
            .header("Connection-Id", connectionId)
            .header("Provider-Config-Key", providerConfigKey)
            .retrieve()
            .body(CompanyInfo.class);
}

The application doesn't send QuickBooks credentials with this request. It sends the Nango connection_id and provider configuration key, and Nango uses the credentials associated with that connection when forwarding the request to QuickBooks.

The important part here is the two headers:

Connection-Id: <nango-connection-id>
Provider-Config-Key: quickbooks-sandbox

They tell Nango which connection and provider configuration to use. Nango then makes the authenticated request to the connected QuickBooks account.

The QuickBooks endpoint itself is:

GET /v3/company/{realmId}/companyinfo/{realmId}

A successful response from the QuickBooks Sandbox looks like:

{
  "CompanyName": "Sandbox Company US c56a",
  "LegalName": "Sandbox Company US c56a",
  "Country": "US",
  "FiscalYearStartMonth": "January"
}

This response came from the QuickBooks Sandbox through Nango; it isn't a mocked response.

This made the integration boundary much clearer: Spring Boot decides which tenant is requesting data and which QuickBooks resource to retrieve, while Nango handles the authenticated connection to QuickBooks.

9. Reading Customers and Invoices

Once the company request is working, the same connection can be used to retrieve customers and invoices. The application exposes:

GET /api/tenants/{tenantId}/accounting/customers
GET /api/tenants/{tenantId}/accounting/invoices

For example:

curl "http://localhost:8080/api/tenants/tenant-1/accounting/customers?limit=2"

curl "http://localhost:8080/api/tenants/tenant-1/accounting/invoices?limit=2"

For customers, the service sends a QuickBooks query through the Nango Proxy:

SELECT * FROM Customer MAXRESULTS {limit}

A response from the Sandbox looks like:

[
  {
    "Id": "8",
    "DisplayName": "0969 Ocean View Road",
    "GivenName": "Sasha",
    "FamilyName": "Tillou",
    "CompanyName": "Freeman Sporting Goods",
    "Active": true,
    "Balance": 477.5
  }
]

The invoice endpoint follows the same approach:

SELECT * FROM Invoice MAXRESULTS {limit}

For example:

[
  {
    "Id": "130",
    "DocNumber": "1037",
    "TxnDate": "2026-09-06",
    "DueDate": "2026-10-06",
    "TotalAmt": 362.07,
    "Balance": 362.07,
    "CustomerRef": {
      "value": "24",
      "name": "Sonnenschein Family Store"
    }
  }
]

Both endpoints use the same tenant-to-connection mapping and realmId resolution described in the previous sections. The client only needs to provide the application-level tenantId; the backend finds the corresponding Nango connection_id, resolves the QuickBooks realmId, and reuses the connection for the request. There is no separate OAuth flow for customers and invoices.

At this point, the integration is doing what I originally set out to build: once a tenant's QuickBooks connection is established, the backend can use that connection to retrieve different types of accounting data.

10. Handling Errors from Nango and QuickBooks

Getting the first successful response is only part of an integration. A connection can be missing, QuickBooks can reject a request, or the API can rate-limit the application. I didn't want those errors to leak directly out of the Nango client, so I handle Nango's responses in the client layer and convert them into application-level exceptions.

Nango can return different status codes depending on where the failure happened:

404: the requested Nango connection doesn't exist.
424: Nango could not complete the request because of an upstream provider error.
429: a rate limit was reached.

For 429, the response can also include a Retry-After header, which gives the application information about when it can try again.

I handle these responses in the Nango client instead of checking status codes inside every service:

if (status == 404) {
    throw new NangoConnectionNotFoundException(
            "Nango connection not found"
    );
}

if (status == 424) {
    throw new NangoActionException(
            error.error().message(),
            error.error().upstream()
    );
}

if (status == 429) {
    String retryAfter =
            response.getHeaders()
                    .getFirst("Retry-After");

    throw new NangoRateLimitException(
            "Nango rate limit exceeded",
            retryAfter
    );
}


}

For 424, I preserve the upstream error information so the application can expose a more useful failure reason. I then use Spring's @RestControllerAdvice to convert these exceptions into ProblemDetail responses:

@ExceptionHandler(NangoConnectionNotFoundException.class)
public ProblemDetail handleConnectionNotFound(
        NangoConnectionNotFoundException ex) {

    ProblemDetail problem =
            ProblemDetail.forStatusAndDetail(
                    HttpStatus.NOT_FOUND,
                    ex.getMessage()
            );

    problem.setTitle("Accounting Connection Not Found");
    return problem;

}

This keeps the Nango-specific error handling inside the integration layer while giving the frontend a consistent API response.

Why this matters

The company, customer, and invoice endpoints all use the same Nango client. Keeping the error handling there means the same behaviour is applied across the accounting endpoints instead of repeating try/catch logic in each controller.

QuickBooks OAuth can also fail

QuickBooks also has its own OAuth token lifecycle, including refresh-token rotation and invalid or revoked refresh tokens. Nango has documented these cases in its QuickBooks OAuth write-up. My Spring Boot application doesn't implement the QuickBooks token refresh lifecycle itself; Nango handles that provider authentication lifecycle.

There is also a trade-off to using an integration layer: Nango becomes another runtime dependency between the application and the provider. For a product with only one or two integrations, implementing the provider connection directly may be reasonable. The value becomes more apparent as the number of integrations and connected accounts grows.

Next, we'll look at another part of the integration that isn't part of the normal request flow: Nango webhooks.

11. Adding Webhooks

The API requests so far are initiated by the application. Webhooks cover the other side of the integration: when Nango sends an event back to the application.

I added a webhook endpoint:

POST /api/webhooks/nango

he endpoint verifies Nango's HMAC-SHA256 signature before processing the payload. Because the signature is calculated from the raw request body, I added WebhookContentCachingFilter to keep the original body available during verification.

The implementation is split into three classes:

NangoWebhookController: receives the webhook and handles the event.
NangoWebhookVerifier: verifies the HMAC-SHA256 signature.
NangoWebhookPayload: represents the incoming event.

For an auth creation event, the webhook uses the organization_id tag that was added to the Connect Session to identify the tenant. It then stores the new Nango connectionId in TenantRepository.

12. Testing

The test suite covers the parts of the integration that can be tested without a live QuickBooks connection. MockWebServer is used to mock Nango API responses, while MockMvc covers the Spring Boot endpoints. The tests cover Connect Session request serialization, Nango Proxy headers, Nango 404, 424, and 429 responses, webhook signature verification, and tenant accounting endpoints.

Run the tests with:

mvn test

The current suite contains 12 tests, all passing. I used the QuickBooks Sandbox separately for live verification. This keeps the automated tests deterministic while still letting me verify the integration against the actual provider.

13. What Nango Handles vs. What Spring Boot Handles

After building the integration, the responsibilities became fairly clear.

14. What I Learned

Building the integration exposed a few things that are easy to miss when looking at OAuth only from the API documentation. Connection mapping, provider-specific fields such as QuickBooks realmId, error handling, and webhooks all become important once the happy path is working.

I also found that the Java SDK wasn't required to get started. The current Nango Java backend documentation points developers to the REST API, so I built a small Java client using Spring's RestClient. This made the integration work well with the rest of the Spring Boot application and gave me a better understanding of what Nango is actually abstracting from the application.

15. A Few Things I'd Improve

The project currently focuses on the main integration flow: connecting QuickBooks, mapping tenants to Nango connections, retrieving connection details, making requests through Nango, handling errors, and testing the integration.

If this were going into a larger application, I'd replace the in-memory tenant-to-connection mapping with persistent storage and extend the connection lifecycle to handle tenants disconnecting and reconnecting their QuickBooks accounts. I'd also add background syncing and more provider-specific handling for cases such as pagination and rate limits.

For this project, I kept the scope smaller so I could focus on understanding the integration itself rather than building a complete accounting product.

16. Conclusion

Building this project gave me a much better idea of what it actually takes to integrate a service like QuickBooks. Making the API call was not the hard part. Most of the work was around the connection itself: setting up OAuth, connecting the right account to the right tenant, dealing with QuickBooks-specific details like realmId, handling errors and rate limits, and working with webhooks.

Building it in Java also helped me understand what Nango takes care of and what still belongs in the application. I didn't have to build the QuickBooks authentication and token handling myself. Nango manages the provider connection and lets the application make authenticated requests through its Proxy. My Spring Boot application still handles the tenants, connection mapping, business logic, API responses, and application-level errors.

I also wanted to make sure this worked with a real provider, not just mocked responses. I tested the complete flow with a QuickBooks Sandbox—from creating the Connect Session and completing OAuth to retrieving company information, customers, and invoices. Going through that process gave me a much clearer understanding of where Nango fits into a Java/Spring Boot application.

17. Useful Nango References

A few Nango resources I used while building and testing the integration:

These are useful if you want to go deeper into the provider-specific OAuth behaviour or the Nango API used in this project.

Monitoring Spring Boot Applications with OpenObserve: A Comprehensive Guide to Logs and Traces

Abhishek Dhiman — Mon, 27 Jul 2026 20:00:01 +0000

When your system spans multiple services, understanding what's happening under the hood becomes crucial for debugging, performance optimization, and maintaining reliability. This is where observability comes in.

OpenObserve, an open-source observability platform, offers a powerful, cost-effective solution for collecting and visualizing logs, traces, and metrics. In this guide, I'll show you how to integrate OpenObserve with a Spring Boot application, including a multi-service architecture example that demonstrates real-world monitoring scenarios.

What you'll learn:

The importance of observability in modern applications
How to set up OpenObserve with Docker
Integrating OpenTelemetry for distributed tracing
Sending structured logs directly to OpenObserve
Analyzing traces and logs together for faster debugging
Error simulation and monitoring in action

Video Tutorial: Watch the complete walkthrough on YouTube

Why Observability Matters

Before diving into the technical implementation, let's understand why observability is critical:

1. Troubleshooting Distributed Systems

In a microservices architecture, a single user request might traverse multiple services. Without proper tracing, finding the root cause of an error becomes like finding a needle in a haystack.

2. Performance Optimization

Understanding which services are slow and why helps you optimize critical paths.

3. Proactive Issue Detection

Monitoring logs and traces allows you to detect and resolve issues before they impact users.

4. Compliance and Auditing

Having a complete record of what happened in your system helps with compliance requirements.

5. Business Intelligence

Observability data can reveal patterns in user behavior and system usage.

What We're Building

We'll build a full-stack e-commerce monitoring demonstration featuring:

A React frontend (Amazon-style store)
A Spring Boot 3 backend with distributed microservices
OpenObserve for centralized logging and tracing

Architecture Overview

┌────────────────────────────────────────────────────────┐
│             React Frontend (Port 3000)                 │
└───────────────────────────┬────────────────────────────┘
                            │ HTTP POST /api/orders/checkout
                            ▼
┌────────────────────────────────────────────────────────┐
│           order-service Gateway (Port 8080)            │
└───────┬───────────────────┬────────────────────┬───────┘
        │ HTTP POST         │ HTTP POST          │ HTTP POST
        ▼                   ▼                    ▼
┌──────────────┐   ┌────────────────┐   ┌─────────────────────┐
│  inventory-  │   │ payment-service│   │ fulfillment-service │
│   service    │   │  (Port 8082)   │   │     (Port 8083)     │
│ (Port 8081)  │   └────────────────┘   └─────────────────────┘
└──────────────┘

The stack consists of 4 independent Spring Boot microservices:

order-service (localhost:8080): Primary API Gateway & Order Checkout Coordinator
inventory-service (localhost:8081): Stock management
payment-service (localhost:8082): Payment processing
fulfillment-service (localhost:8083): Shipping logistics

All services send logs and traces to OpenObserve, enabling end-to-end visibility.

Prerequisites

Before we begin, ensure you have:

Docker Desktop installed and running
Node.js (v18+) installed
Java 17 JDK installed
Maven (or use the auto-download in the provided script)
PowerShell (Windows) or terminal for your OS

Step 1: Setting Up OpenObserve

1.1. Docker Compose Configuration

Create a docker-compose.yml file:

version: '3.8'

services:
  openobserve:
    image: openobserve/openobserve:latest
    container_name: openobserve
    restart: always
    environment:
      - ZO_ROOT_USER_EMAIL=root@example.com
      - ZO_ROOT_USER_PASSWORD=ComplexPassword123
      - ZO_HTTP_PORT=5080
      - ZO_DATA_DIR=/data
    ports:
      - "5080:5080"
    volumes:
      - openobserve-data:/data

volumes:
  openobserve-data:

This configuration:

Pulls the official OpenObserve image
Sets up default credentials (root@example.com / ComplexPassword123)
Exposes the UI on port 5080
Persists data using a Docker volume

1.2. Start OpenObserve

Run the following command:

docker-compose up -d

Wait a few seconds for the container to initialize, then navigate to http://localhost:5080 and log in with:

Email: root@example.com
Password: ComplexPassword123

OpenObserve login page with default credentials

Step 2: Spring Boot Application Configuration

2.1. Maven Dependencies

Add the following dependencies to your pom.xml:

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>io.opentelemetry</groupId>
            <artifactId>opentelemetry-bom</artifactId>
            <version>1.35.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependencies>
    <!-- Spring Boot Starters -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-actuator</artifactId>
    </dependency>

    <!-- Micrometer & OpenTelemetry Tracing -->
    <dependency>
        <groupId>io.micrometer</groupId>
        <artifactId>micrometer-tracing-bridge-otel</artifactId>
    </dependency>
    <dependency>
        <groupId>io.opentelemetry</groupId>
        <artifactId>opentelemetry-exporter-otlp</artifactId>
    </dependency>

    <dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
        <optional>true</optional>
    </dependency>
</dependencies>

2.2. Application Configuration

Add OpenObserve configuration to application.yml:

server:
  port: 8080

spring:
  application:
    name: order-service

management:
  endpoints:
    web:
      exposure:
        include: health,info,metrics,prometheus,env
  tracing:
    sampling:
      probability: 1.0
  otlp:
    tracing:
      endpoint: http://localhost:5080/api/default/v1/traces
      headers:
        Authorization: "Basic cm9vdEBleGFtcGxlLmNvbTpDb21wbGV4UGFzc3dvcmQxMjM="
  opentelemetry:
    resource-attributes:
      service.name: order-service

openobserve:
  url: http://localhost:5080
  auth-header: "Basic cm9vdEBleGFtcGxlLmNvbTpDb21wbGV4UGFzc3dvcmQxMjM="
  organization: default
  stream: default

Note: The Authorization header uses the Base64-encoded credentials. The format is Basic base64(email:password).

Step 3: Implementing Log Forwarding

3.1. The Log Publisher

Create a component that queues and flushes logs to OpenObserve:

package com.example.amzstore.config;

import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.http.HttpEntity;
import org.springframework.http.HttpHeaders;
import org.springframework.http.MediaType;
import org.springframework.scheduling.annotation.EnableScheduling;
import org.springframework.scheduling.annotation.Scheduled;
import org.springframework.stereotype.Component;
import org.springframework.web.client.RestTemplate;

import java.time.Instant;
import java.util.*;
import java.util.concurrent.ConcurrentLinkedQueue;

@Slf4j
@Component
@EnableScheduling
@RequiredArgsConstructor
public class OpenObserveLogPublisher {

    @Value("${openobserve.url:http://localhost:5080}")
    private String openobserveUrl;

    @Value("${openobserve.auth-header:Basic cm9vdEBleGFtcGxlLmNvbTpDb21wbGV4UGFzc3dvcmQxMjM=}")
    private String authHeader;

    private final RestTemplate restTemplate;
    private static final ConcurrentLinkedQueue<Map<String, Object>> logQueue = new ConcurrentLinkedQueue<>();

    public static void queueLog(String level, String loggerName, String message, 
                                String traceId, String spanId) {
        if (loggerName != null && loggerName.contains("OpenObserveLogPublisher")) {
            return;
        }

        Map<String, Object> logEntry = new HashMap<>();
        logEntry.put("_timestamp", Instant.now().toEpochMilli() * 1000);
        logEntry.put("level", level);
        logEntry.put("logger", loggerName != null ? loggerName : "ApplicationLogger");
        logEntry.put("message", message);
        logEntry.put("service_name", "amzstore-backend");
        logEntry.put("trace_id", traceId != null ? traceId : "none");
        logEntry.put("span_id", spanId != null ? spanId : "none");

        logQueue.add(logEntry);
    }

    @Scheduled(fixedRate = 1000)
    public void flushLogsToOpenObserve() {
        if (logQueue.isEmpty()) {
            return;
        }

        List<Map<String, Object>> batch = new ArrayList<>();
        while (!logQueue.isEmpty() && batch.size() < 100) {
            Map<String, Object> entry = logQueue.poll();
            if (entry != null) {
                batch.add(entry);
            }
        }

        if (batch.isEmpty()) return;

        try {
            String endpoint = openobserveUrl + "/api/default/default/_json";
            HttpHeaders headers = new HttpHeaders();
            headers.setContentType(MediaType.APPLICATION_JSON);
            headers.set("Authorization", authHeader);

            HttpEntity<List<Map<String, Object>>> entity = new HttpEntity<>(batch, headers);
            restTemplate.postForEntity(endpoint, entity, String.class);
        } catch (Exception e) {
            log.debug("Failed to send logs to OpenObserve: {}", e.getMessage());
        }
    }
}

3.2. Custom Logback Appender

To automatically capture all log events, create a Logback appender:

package com.example.amzstore.config;

import ch.qos.logback.classic.spi.ILoggingEvent;
import ch.qos.logback.core.AppenderBase;

public class OpenObserveLogbackAppender extends AppenderBase<ILoggingEvent> {

    @Override
    protected void append(ILoggingEvent eventObject) {
        if (eventObject == null) return;

        String traceId = "none";
        String spanId = "none";

        if (eventObject.getMDCPropertyMap() != null) {
            traceId = eventObject.getMDCPropertyMap().getOrDefault("traceId", "none");
            spanId = eventObject.getMDCPropertyMap().getOrDefault("spanId", "none");
        }

        OpenObserveLogPublisher.queueLog(
                eventObject.getLevel().toString(),
                eventObject.getLoggerName(),
                eventObject.getFormattedMessage(),
                traceId,
                spanId
        );
    }
}

3.3. Logback Configuration

Update logback-spring.xml:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <!-- Console Appender -->
    <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
        <encoder>
            <pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{36} [traceId=%X{traceId:-none} spanId=%X{spanId:-none}] - %msg%n</pattern>
        </encoder>
    </appender>

    <!-- OpenObserve Appender -->
    <appender name="OPENOBSERVE" class="com.example.amzstore.config.OpenObserveLogbackAppender">
    </appender>

    <root level="INFO">
        <appender-ref ref="CONSOLE"/>
        <appender-ref ref="OPENOBSERVE"/>
    </root>
</configuration>

Step 4: Distributed Tracing Implementation

4.1. HTTP Logging Interceptor

Create an interceptor to capture all HTTP requests and responses with trace IDs:

package com.example.amzstore.config;

import io.micrometer.tracing.Tracer;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.stereotype.Component;
import org.springframework.web.servlet.HandlerInterceptor;

@Slf4j
@Component
@RequiredArgsConstructor
public class LogInterceptor implements HandlerInterceptor {

    private final Tracer tracer;

    @Override
    public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) {
        String traceId = tracer.currentSpan() != null ? 
            tracer.currentSpan().context().traceId() : "none";
        String spanId = tracer.currentSpan() != null ? 
            tracer.currentSpan().context().spanId() : "none";

        String msg = String.format("HTTP %s %s from %s", 
            request.getMethod(), request.getRequestURI(), request.getRemoteAddr());
        OpenObserveLogPublisher.queueLog("INFO", "HTTP_REQUEST", msg, traceId, spanId);
        return true;
    }

    @Override
    public void afterCompletion(HttpServletRequest request, HttpServletResponse response, 
                               Object handler, Exception ex) {
        String traceId = tracer.currentSpan() != null ? 
            tracer.currentSpan().context().traceId() : "none";
        String spanId = tracer.currentSpan() != null ? 
            tracer.currentSpan().context().spanId() : "none";

        String level = response.getStatus() >= 400 ? "ERROR" : "INFO";
        String msg = String.format("HTTP %s %s completed with status %d", 
            request.getMethod(), request.getRequestURI(), response.getStatus());

        if (ex != null) {
            msg += " Exception: " + ex.getMessage();
        }

        OpenObserveLogPublisher.queueLog(level, "HTTP_RESPONSE", msg, traceId, spanId);
    }
}

package com.example.amzstore.config;

import lombok.RequiredArgsConstructor;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

@Configuration
@RequiredArgsConstructor
public class WebConfig implements WebMvcConfigurer {

    private final LogInterceptor logInterceptor;

    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(logInterceptor);
    }
}

4.2. Manual Tracing in Services

To create custom spans in your services:

import io.micrometer.tracing.ScopedSpan;
import io.micrometer.tracing.Tracer;
import io.opentelemetry.api.trace.Span;
import io.opentelemetry.api.trace.StatusCode;

@Service
@RequiredArgsConstructor
public class OrderService {

    private final Tracer tracer;

    public Order processCheckout(CheckoutRequest request) {
        ScopedSpan span = tracer.startScopedSpan("AuthService :: validateCustomerSession");
        try {
            span.tag("peer.service", "auth-service");
            span.tag("order.id", orderId);
            span.tag("customer.email", email);

            // Your business logic here

            Span.current().setStatus(StatusCode.OK, 
                "AuthService: Customer session token validated successfully");
        } catch (Exception e) {
            span.error(e);
            Span.current().recordException(e);
            Span.current().setStatus(StatusCode.ERROR, "Authentication failed: " + e.getMessage());
            throw e;
        } finally {
            span.end();
        }
    }
}

4.3. Cross-Service Trace Propagation

For HTTP calls between services, the trace context is automatically propagated using W3C Trace Context headers when using RestTemplate:

@Autowired
private RestTemplate restTemplate;

public boolean callInventoryService() {
    // The trace context is automatically propagated via headers
    // No additional code needed - OpenTelemetry handles it!
    restTemplate.postForEntity(inventoryServiceUrl + "/reserve", null, Map.class);
}

Step 5: Running the Demo Application

5.1. Automated Launch Script

The repository includes a PowerShell script that automates the entire setup:

# run-all.ps1
Write-Host "Starting OpenObserve Multi-Microservice E-Commerce Monitoring Stack" -ForegroundColor Cyan

# Kill any existing Java processes
Stop-Process -Name java -Force -ErrorAction SilentlyContinue

# Start OpenObserve
docker-compose up -d

# Check for Maven and download if needed
# ... (Maven setup logic)

# Start all microservices
Start-Process powershell.exe -ArgumentList "-NoExit", "-Command", "& mvn spring-boot:run" -WorkingDirectory "./services/inventory-service"
Start-Process powershell.exe -ArgumentList "-NoExit", "-Command", "& mvn spring-boot:run" -WorkingDirectory "./services/payment-service"
Start-Process powershell.exe -ArgumentList "-NoExit", "-Command", "& mvn spring-boot:run" -WorkingDirectory "./services/fulfillment-service"
Start-Process powershell.exe -ArgumentList "-NoExit", "-Command", "& mvn spring-boot:run" -WorkingDirectory "./backend"

# Start React frontend
npm install --prefix ./frontend
Start-Process powershell.exe -ArgumentList "-NoExit", "-Command", "npm run dev" -WorkingDirectory "./frontend"

5.2. Manual Start

If you prefer to start services manually:

1. Start OpenObserve:

docker-compose up -d

2. Start each microservice (in separate terminals):

cd services/inventory-service
mvn spring-boot:run

cd services/payment-service
mvn spring-boot:run

cd services/fulfillment-service
mvn spring-boot:run

cd backend
mvn spring-boot:run

3. Start the frontend:

cd frontend
npm install
npm run dev

5.3. Access Points

Once everything is running:

React Frontend: http://localhost:3000
OpenObserve Dashboard: http://localhost:5080 (root@example.com / ComplexPassword123)
Order Service API: http://localhost:8080/api/products
Inventory Service: http://localhost:8081/api/inventory/reserve
Payment Service: http://localhost:8082/api/payment/authorize
Fulfillment Service: http://localhost:8083/api/fulfillment/ship

Step 6: Analyzing Logs and Traces in OpenObserve

6.1. Viewing Logs

Navigate to OpenObserve UI (http://localhost:5080)
Click on the Logs tab
Select the stream default
Click Run Query

You'll see structured logs with:

Log level (INFO, WARN, ERROR)
Service name
Message content
Trace ID (for correlation)
Span ID
Timestamp

Structured logs from the Spring Boot microservices showing trace_id correlation

Log Correlation Example: Search for a specific trace_id to see all logs related to a single request:

trace_id = "your-trace-id-here"

6.2. Viewing Traces

Navigate to the Traces tab
Click Run Query to see all traces

Each trace shows:

Service Map: Visual representation of service dependencies
Gantt Chart: Time breakdown of each span
Span Details: Tags, duration, status, and error information
Trace ID: For cross-referencing with logs

Distributed trace showing the complete flow from order-service through all downstream services

Visual representation of service dependencies in the microservices architecture

6.3. Error Detection

The demo includes several failure simulation modes:

Inventory Service Failure: Simulates DB row lock timeout (500 Internal Server Error)
Payment Gateway Failure: Simulates card authorization decline (402 Payment Required)
Fulfillment Service Failure: Simulates carrier API timeout (503 Service Unavailable)
Database Connection Timeout: Simulates HikariCP pool exhaustion (504 Gateway Timeout)

Select any failure mode in the checkout UI to see how errors are captured in logs and traces.

Detailed view of a trace showing the exact span where an error occurred

Step 7: Error Simulation and Monitoring

7.1. Triggering Errors

In the React frontend, you can simulate different failure scenarios:

// In Checkout UI, select from dropdown:
// - INVENTORY: InventoryOutOfStockException
// - PAYMENT: PaymentGatewayDeclinedException  
// - SHIPPING: CarrierServiceUnavailableException
// - DATABASE: DatabaseConnectionTimeoutException

Checkout page with failure mode selector for testing error scenarios

7.2. Error Response Example

When a payment failure occurs:

HTTP Response:

{
  "success": false,
  "message": "Order checkout failed: PaymentGatewayDeclinedException: Card authorization declined by issuing bank (Code 402)",
  "traceId": "a1b2c3d4e5f6...",
  "spanId": "g7h8i9j0...",
  "data": {
    "orderId": "ORD-1701234567890",
    "status": "FAILED",
    "failureReason": "PaymentGatewayDeclinedException: Card authorization declined by issuing bank (Code 402)"
  }
}

7.3. Monitoring Errors

In OpenObserve Logs:

level: ERROR
message: "[payment-service] Payment authorization REJECTED for OrderID: ORD-1701234567890! Insufficient funds or invalid CVV."
trace_id: "a1b2c3d4e5f6..."

In OpenObserve Traces:

The trace shows the exact span where the error occurred
Status: ERROR with detailed error message
The entire request flow is visible, making it easy to pinpoint the failure point

Step 8: Key Features and Benefits

8.1. Multi-Hop Distributed Tracing

With W3C Trace Context headers, your traces automatically connect across service boundaries. Each HTTP call propagates the trace ID, creating a complete picture of request flow.

Services visible in OpenObserve:

order-service
inventory-service
payment-service
fulfillment-service

8.2. Live Log Correlation

Every log entry includes trace_id and span_id, allowing you to:

Filter logs by trace ID to see all logs from a single request
Jump from trace to logs and back for deeper investigation
Understand the timing and sequence of operations

8.3. Structured Logging

Logs are sent as JSON, enabling:

Easy filtering and searching
Aggregation and analysis
Integration with alerting systems

8.4. Cost-Effective Observability

OpenObserve is:

Open-source (free to use)
Efficient (compresses data)
Scalable (handles millions of events)

8.5. Unified Dashboard

View logs, traces, and metrics in one place:

No context switching between tools
Full visibility into application health
Faster incident response

Conclusion

Monitoring Spring Boot applications with OpenObserve is straightforward and provides powerful insights into your application's behavior. By implementing distributed tracing and structured logging, you gain:

End-to-end visibility across your entire system
Faster debugging with correlated logs and traces
Better performance through bottleneck identification
Cost-effective observability without vendor lock-in

The demo application and code provided in this guide give you a complete, working example that you can adapt for your own Spring Boot applications. Whether you're running a simple microservice or a complex distributed system, OpenObserve provides the observability you need to build reliable, maintainable applications.

Resources

GitHub Repository: https://github.com/abhishek-dhnma/OpenObserve-Demo-with-Springboot
Video Tutorial: https://youtu.be/fixVzjRBbcE
OpenObserve Documentation: https://openobserve.ai/docs/
OpenTelemetry Java: https://opentelemetry.io/docs/instrumentation/java/
Spring Boot Actuator: https://docs.spring.io/spring-boot/docs/current/reference/html/actuator.html

DEV Community: Abhishek Dhiman

Building a Multi-Tenant QuickBooks Integration with Spring Boot and Nango

1. Prerequisites

2. Create a QuickBooks Developer App

3. Create a QuickBooks Sandbox Company

4. Configure QuickBooks in Nango

5. Create a Nango Connect Session from Spring Boot

One small addition I'd make

6. Complete the QuickBooks OAuth Connection

7. Resolve the Nango Connection and realmId

8. Making the First QuickBooks API Request

9. Reading Customers and Invoices

10. Handling Errors from Nango and QuickBooks

Why this matters

QuickBooks OAuth can also fail

11. Adding Webhooks

12. Testing

13. What Nango Handles vs. What Spring Boot Handles

14. What I Learned

15. A Few Things I'd Improve

16. Conclusion

17. Useful Nango References

Monitoring Spring Boot Applications with OpenObserve: A Comprehensive Guide to Logs and Traces

Why Observability Matters

1. Troubleshooting Distributed Systems

2. Performance Optimization

3. Proactive Issue Detection

4. Compliance and Auditing

5. Business Intelligence

What We're Building

Architecture Overview

Prerequisites

Step 1: Setting Up OpenObserve

1.1. Docker Compose Configuration

1.2. Start OpenObserve

Step 2: Spring Boot Application Configuration

2.1. Maven Dependencies

2.2. Application Configuration

Step 3: Implementing Log Forwarding

3.1. The Log Publisher

3.2. Custom Logback Appender

3.3. Logback Configuration

Step 4: Distributed Tracing Implementation

4.1. HTTP Logging Interceptor

4.2. Manual Tracing in Services

4.3. Cross-Service Trace Propagation

Step 5: Running the Demo Application

5.1. Automated Launch Script

5.2. Manual Start

5.3. Access Points

Step 6: Analyzing Logs and Traces in OpenObserve

6.1. Viewing Logs

6.2. Viewing Traces

6.3. Error Detection

Step 7: Error Simulation and Monitoring

7.1. Triggering Errors

7.2. Error Response Example

7.3. Monitoring Errors

Step 8: Key Features and Benefits

8.1. Multi-Hop Distributed Tracing

8.2. Live Log Correlation

8.3. Structured Logging

8.4. Cost-Effective Observability

8.5. Unified Dashboard

Conclusion

Resources

7. Resolve the Nango Connection and `realmId`