> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apitally.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Setup guide for Spring Boot

> Just a few simple steps to get started with Apitally.

export const language_0 = "java"

export const framework_0 = "Spring Boot"

This page guides you through the steps of configuring your [Spring Boot](https://spring.io/projects/spring-boot) application to work with Apitally. If you don't have an account yet, now would be a good time to [sign up](https://app.apitally.io/?signup).

Once you're done with this guide, you will be able to:

* Get detailed metrics on API usage, errors, and performance
* Track API adoption and usage by individual consumers
* Log individual API requests, responses, and correlated application logs
* See what's causing slow API requests with traces
* Monitor uptime and set up custom alerts

## Create app

To get started, create a new app in the [Apitally dashboard](https://app.apitally.io/apps) and select {framework_0} as your framework.

<img src="https://assets.apitally.io/docs/2025-12-08/create-app.webp" alt="Create app" className="rounded-xl" />

You can also configure the environments (e.g. `prod` and `dev`) for your app, or simply accept the defaults.

After submitting, you will see tailored setup instructions for your app. These include code snippets you can copy and paste into your project.

<Note>
  The **client ID** provided in the setup instructions uniquely identifies your app for the purpose of data ingestion only. It does not grant any kind of read access to your data.
</Note>

## Enable Apitally

Add the [Apitally SDK](/sdk-reference/java/overview) to your project's dependencies.

<CodeGroup>
  ```xml Maven theme={null}
  <dependency>
    <groupId>io.apitally</groupId>
    <artifactId>apitally</artifactId>
    <version>[0.1.0,)</version>
  </dependency>
  ```

  ```groovy Gradle theme={null}
  dependencies {
    implementation 'io.apitally:apitally:+'
  }
  ```
</CodeGroup>

Next, add the `@UseApitally` annotation to your Spring Boot application class.

```java Application.java {6} theme={null}
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

import io.apitally.spring.UseApitally;

@UseApitally
@SpringBootApplication
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}
```

Then configure Apitally in your `application.yml` file and provide the client ID for your app.
You'll find the client ID on the *Setup instructions* page in the Apitally dashboard, which is displayed immediately after creating the app.

```yaml application.yml theme={null}
apitally:
  client-id: "your-client-id"
  env: "dev" # or "prod" etc.
```

Deploy your application with these changes, or restart if you're testing locally.

<Check>
  At this point the basic setup for your application is complete and you will start seeing data in the Apitally dashboard.
</Check>

## Identify consumers

To analyze and filter API traffic by consumers, you can associate requests with consumer identifiers in your application.

In most cases, use the authenticated identity to identify the consumer.
The identifier should be a string, such as a username, email address, or any other unique identifier.

Optionally, you can also provide a display name and group for each consumer.

To associate requests with consumers, set the `apitallyConsumer` attribute on the request. You could do this in a filter or interceptor, for example.

<CodeGroup>
  ```java Identifier only theme={null}
  import org.springframework.security.core.Authentication;
  import org.springframework.security.core.context.SecurityContextHolder;
  import org.springframework.web.filter.OncePerRequestFilter;
  import jakarta.servlet.FilterChain;
  import jakarta.servlet.ServletException;
  import jakarta.servlet.http.HttpServletRequest;
  import jakarta.servlet.http.HttpServletResponse;

  public class ConsumerIdentificationFilter extends OncePerRequestFilter {
      @Override
      protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain chain)
              throws ServletException, IOException {
          Authentication auth = SecurityContextHolder.getContext().getAuthentication();
          if (auth != null && auth.isAuthenticated()) {
              request.setAttribute("apitallyConsumer", auth.getName());
          }
          chain.doFilter(request, response);
      }
  }
  ```

  ```java With name and group theme={null}
  import org.springframework.security.core.Authentication;
  import org.springframework.security.core.context.SecurityContextHolder;
  import org.springframework.web.filter.OncePerRequestFilter;
  import jakarta.servlet.FilterChain;
  import jakarta.servlet.ServletException;
  import jakarta.servlet.http.HttpServletRequest;
  import jakarta.servlet.http.HttpServletResponse;

  import io.apitally.spring.ApitallyConsumer;

  public class ConsumerIdentificationFilter extends OncePerRequestFilter {
      @Override
      protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain chain)
              throws ServletException, IOException {
          Authentication auth = SecurityContextHolder.getContext().getAuthentication();
          if (auth != null && auth.isAuthenticated()) {
              User user = (User) auth.getPrincipal();
              request.setAttribute("apitallyConsumer", new ApitallyConsumer(
                  user.getUsername(), // identifier
                  user.getFullName(), // name
                  user.getRole() // group
              ));
          }
          chain.doFilter(request, response);
      }
  }
  ```
</CodeGroup>

<Check>
  The *Consumers* dashboard now shows all consumers that have made requests to your application. You can also filter other dashboards by consumer.
</Check>

## Configure request logging

Logging of individual requests and responses is disabled by default to protect potentially sensitive data.
If you enable it, you can configure in detail what parts of the request and response should be logged.
You can also mask sensitive information (e.g. in headers) and exclude certain requests from logging.

The SDK applies [default masking rules](/data-privacy#data-masking) for common sensitive headers, query parameters and request/response body fields.

{language_0 == "python" && <p>Check out the <a href="/sdk-reference/python/configuration">SDK reference</a> to learn more about the request logging configuration options.</p>}

{language_0 == "javascript" && <p>Check out the <a href="/sdk-reference/javascript/configuration">SDK reference</a> to learn more about the request logging configuration options.</p>}

{language_0 == "go" && <p>Check out the <a href="/sdk-reference/go/configuration">SDK reference</a> to learn more about the request logging configuration options.</p>}

Check out the <a href="/sdk-reference/java/configuration">SDK reference</a> to learn more about the request logging configuration options.

<CodeGroup>
  ```yaml Basic example theme={null}
  apitally:
    client-id: "your-client-id"
    env: "dev" # or "prod" etc.
    request-logging:
      enabled: true
      request-headers-included: true
      request-body-included: true
      response-body-included: true
      log-capture-enabled: true
  ```

  ```yaml Advanced example theme={null}
  apitally:
    client-id: "your-client-id"
    env: "dev" # or "prod" etc.
    request-logging:
      enabled: true
      query-params-included: true
      request-headers-included: true
      request-body-included: true
      response-headers-included: true
      response-body-included: true
      exception-included: true
      log-capture-enabled: true
      # Mask query parameters using regex
      query-param-mask-patterns:
        - "^card_number$"
      # Mask headers using regex
      header-mask-patterns:
        - "^X-Sensitive-Header$"
      # Mask request/response body fields using regex
      body-field-mask-patterns:
        - "^sensitive_field$"
      # Exclude paths from request logging using regex (common health check paths are excluded by default)
      path-exclude-patterns:
        - "/metrics$"
      # Use callbacks for advanced masking and exclusion logic
      callbacks-class: "com.example.MyRequestLoggingCallbacks"
  ```

  ```java RequestLoggingCallbacks.java theme={null}
  import io.apitally.common.RequestLoggingCallbacks;
  import io.apitally.common.dto.Request;
  import io.apitally.common.dto.Response;

  public class MyRequestLoggingCallbacks implements RequestLoggingCallbacks {
      @Override
      public byte[] maskRequestBody(Request request) {
          // Mask request/response body with custom logic via callbacks (e.g. for admin endpoints)
          // The callback should return null to mask the whole body, or return the (modified) raw body
          if (request.getPath().startsWith("/admin/")) {
              return null; // Mask the whole body for admin endpoints
          }
          return request.getBody();
      }

      @Override
      public byte[] maskResponseBody(Request request, Response response) {
          if (request.getPath().startsWith("/admin/")) {
              return null; // Mask the whole body for admin endpoints
          }
          return response.getBody();
      }

      @Override
      public boolean shouldExclude(Request request, Response response) {
          // Exclude requests from logging with custom logic via callback (e.g. exclude requests from a specific consumer)
          // The callback should return true to exclude the request
          return "some-consumer".equals(request.getConsumer());
      }
  }
  ```
</CodeGroup>

<Check>
  The *Request logs* dashboard now shows individual requests handled by your application. You can filter, search, and inspect them in detail.
</Check>