Sign Up
Open in ChatGPT Open in Claude Open in Perplexity

Springboot SDK Guide

This guide shows how to attach the OpenTelemetry Java agent to your Spring Boot application and install the monoscope SDK. OpenTelemetry sends traces, metrics and logs. The SDK adds request and response details, error reports and outgoing request monitoring.


Prerequisites

You need a monoscope project and its API key. If you do not have them yet, follow Get started.

Set Up With Your Coding Agent

Your coding agent can add the instrumentation for you. Install the monoscope skills and the monoscope CLI:

# Claude Code
claude plugin marketplace add monoscope-tech/skills
claude plugin install monoscope-skills@monoscope-skills

# Cursor, Codex, Cline and other agents
npx skills add monoscope-tech/skills

# monoscope CLI
curl https://monoscopehq.com/install.sh | sh
monoscope auth login

Then ask your agent to instrument the project. In Claude Code, run:

/monoscope-skills:instrument Add OpenTelemetry for monoscope to this project

The skill uses the CLI to add the SDK and to make sure that events arrive. To do the setup by hand, follow the steps below. For help from a person, email us.

Installation

Add the dependency to the <dependencies> section of your pom.xml file:

<dependency>
  <groupId>io.apitoolkit.springboot</groupId>
  <artifactId>apitoolkit-springboot</artifactId>
  <version>2.0.9</version>
</dependency>

OpenTelemetry Setup

The SDK adds its data to OpenTelemetry spans, so the OpenTelemetry Java agent must be attached. Download the agent:

curl -L -O https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/latest/download/opentelemetry-javaagent.jar

Set Up OpenTelemetry Variables

Set your API key and the monoscope endpoint:

export OTEL_EXPORTER_OTLP_ENDPOINT="http://otelcol.monoscope.tech:4317"
export OTEL_SERVICE_NAME="my-service" # Specifies the name of the service.
export OTEL_RESOURCE_ATTRIBUTES="x-api-key=YOUR_API_KEY" # Adds your API KEY to the resource.
export OTEL_EXPORTER_OTLP_PROTOCOL="grpc" # Specifies the protocol to use for the OpenTelemetry exporter.

Tip

Replace YOUR_API_KEY with an API key from Settings > API Keys in monoscope.

Run the application with the agent attached:

java -javaagent:<PATH-TO>/opentelemetry-javaagent.jar -jar target/your_app.jar

Or, with Maven:

mvn spring-boot:run -Dspring-boot.run.jvmArguments="-javaagent:<PATH-TO>/opentelemetry-javaagent.jar"

monoscope SDK Configuration

Configure the SDK with these optional properties in your src/main/resources/application.properties file:

# Capture request and response bodies (off by default)
apitoolkit.captureRequest_body=true
apitoolkit.captureResponse_body=true
apitoolkit.serviceName=my-service
apitoolkit.serviceVersion=2.0
# Comma-separated lists
apitoolkit.tags=value1,value2
apitoolkit.redactHeaders=Authorization,X-Api-Key
apitoolkit.redactRequestBody=$.password,$.creditCardNumber
apitoolkit.redactResponseBody=$.password,$.creditCardNumber
apitoolkit.debug=false

Then add the @EnableAPIToolkit annotation to your application class:

package com.example.demo;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import io.apitoolkit.springboot.annotations.EnableAPIToolkit;
import org.springframework.web.bind.annotation.*;

@SpringBootApplication
@EnableAPIToolkit
@RestController
public class DemoApplication {

  public static void main(String[] args) {
    SpringApplication.run(DemoApplication.class, args);
  }

  @GetMapping("/greet/{name}")
  public String getUser(@PathVariable String name) {
    return "Hello, " + name;
  }
}

Redacting Sensitive Data

<div class=”callout”> <i class=”fa-solid fa-circle-info”></i> <p><code>authorization</code>, <code>cookie</code>, <code>set-cookie</code> and <code>proxy-authorization</code> headers are always redacted, on requests and responses and on outgoing calls, whatever you configure. Header names match case-insensitively.</p> </div>

If you have fields that are sensitive and should not be sent to monoscope servers, you can mark those fields to be redacted (the fields will never leave your servers).

To mark a field for redacting via this SDK, you need to provide additional configuration options to the application.properties file with paths to the fields that should be redacted. There are three arguments you can provide to configure what gets redacted, namely:

  1. redactHeaders: A list of HTTP header keys.
  2. redactRequestBody: A list of JSONPaths from the request body.
  3. redactResponseBody: A list of JSONPaths from the response body.

JSONPath is a query language used to select and extract data from JSON files. For example, given the following sample user data JSON object:

{
  "user": {
    "name": "John Martha",
    "email": "[email protected]",
    "addresses": [
      {
        "street": "123 Main St",
        "city": "Anytown",
        "state": "CA",
        "zip": "12345"
      },
      {
        "street": "123 Main St",
        "city": "Anytown",
        "state": "CA",
        "zip": "12345"
      }
    ],
    "credit_card": {
      "number": "4111111111111111",
      "expiration": "12/28",
      "cvv": "123"
    }
  }
}

Examples of valid JSONPath expressions would be:

JSONPath Description
$.user.addresses[*].zip In this case, monoscope will replace the zip field in all the objects of the addresses list inside the user object with the string [CLIENT_REDACTED].
$.user.credit_card In this case, monoscope will replace the entire credit_card object inside the user object with the string [CLIENT_REDACTED].

Tip

To learn more about JSONPaths, please take a look at the official docs or use this JSONPath Evaluator to validate your JSONPath expressions.

You can also use our JSON Redaction Tool to preview what the final data sent from your API to monoscope will look like, after redacting any given JSON object.


Here’s an example of what the configuration would look like with redacted fields:

apitoolkit.redactHeaders=content-type,Authorization,HOST
apitoolkit.redactRequestBody=$.user.email,$.user.addresses
apitoolkit.redactResponseBody=$.users[*].email,$.users[*].credit_card

Note

  • The apitoolkit.redactHeaders property expects a list of case-insensitive headers as strings.
  • The apitoolkit.redactRequestBody and apitoolkit.redactResponseBody properties expect a list of JSONPaths as strings.
  • The list of items to be redacted will be applied to all endpoint requests and responses on your server.

Error Reporting

With monoscope, you can track and report different unhandled or uncaught errors, API issues, and anomalies at different parts of your application. This will help you associate more detail and context from your backend with any failing customer request.

To report an error by hand, call the static APErrors.reportError() method with the request and the exception:

package com.example.demo;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.web.bind.annotation.*;
import jakarta.servlet.http.HttpServletRequest;

import io.apitoolkit.springboot.APErrors;
import io.apitoolkit.springboot.annotations.EnableAPIToolkit;

@EnableAPIToolkit
@SpringBootApplication
@RestController
public class DemoApplication {

  public static void main(String[] args) {
    SpringApplication.run(DemoApplication.class, args);
  }

  @GetMapping("/hello")
  public String hello(@RequestParam(value = "name", defaultValue = "World") String name, HttpServletRequest request) {
    try {
      System.out.print(1 / 0); // This will throw an ArithmeticException
    } catch (Exception e) {
      // Report the error to monoscope
      APErrors.reportError(request, e);
    }
    return String.format("Hello %s!", name);
  }
}

Monitoring Outgoing Requests

Outgoing requests are external API calls you make from your API. By default, monoscope monitors all requests users make from your application and they will all appear in the Log Explorer page. To see only outgoing requests, open the Outgoing tab of the API Catalog. Each outgoing request links to the incoming request that triggered it.

To monitor outgoing requests made with the Apache HTTP client, use the ObserveRequest class. Create an instance, then call createHttpClient() with the current request and an optional URL path pattern (for URLs with path parameters):

package com.example.demo;

import java.util.List;

import org.apache.http.client.methods.CloseableHttpResponse;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.util.EntityUtils;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import io.apitoolkit.springboot.annotations.EnableAPIToolkit;
import io.apitoolkit.springboot.integrations.ObserveRequest;
import jakarta.servlet.http.HttpServletRequest;

import org.springframework.web.bind.annotation.*;

@SpringBootApplication
@EnableAPIToolkit
@RestController
public class DemoApplication {

  public static void main(String[] args) {
    SpringApplication.run(DemoApplication.class, args);
  }

  // Create an instance of the ObserveRequest class
  private ObserveRequest observingClient = new ObserveRequest(
    // Optional parameters to redact headers and request/response body
    List.of("content-type", "Authorization", "HOST"),
    List.of("$.user.email", "$.user.addresses"),
    List.of("$.users[*].email", "$.users[*].credit_card")
  );

  @GetMapping("/hello")
  public String hello(HttpServletRequest request) {
    // Use the observingClient instance to create an HTTP Client
    CloseableHttpClient httpClient = observingClient.createHttpClient(request, "/posts/{post_id}");
    try {
      HttpGet httpGet = new HttpGet("https://jsonplaceholder.typicode.com/posts/1");
      CloseableHttpResponse response = httpClient.execute(httpGet);
      String responseStr = EntityUtils.toString(response.getEntity());
      return responseStr;
    } catch (Exception e) {
      e.printStackTrace();
      return "Error occurred while processing the request...";
    }
  }
}

Non-HTTP Entry Points (Background Jobs, Workers, CLIs)

The Spring Boot servlet filter only covers HTTP requests. The OpenTelemetry Java agent already auto-instruments most of the rest — including @Scheduled, @KafkaListener, @RabbitListener, @JmsListener, Spring Batch jobs, and Quartz triggers — so verify the agent is attached before doing manual work. Run with:

java -javaagent:opentelemetry-javaagent.jar -jar app.jar

Anything the agent doesn’t cover (custom thread pools, CommandLineRunner startup work, manual queue consumers, BackgroundService-style polling beans) needs a manual span. Use the OpenTelemetry API:

import io.opentelemetry.api.GlobalOpenTelemetry;
import io.opentelemetry.api.trace.Span;
import io.opentelemetry.api.trace.SpanKind;
import io.opentelemetry.api.trace.StatusCode;
import io.opentelemetry.api.trace.Tracer;
import io.opentelemetry.context.Scope;

@Component
public class EmailWorker {
    private static final Tracer tracer =
        GlobalOpenTelemetry.getTracer("my-service-worker");

    public void processEmail(EmailJob job) {
        Span span = tracer.spanBuilder("email.send")
            .setSpanKind(SpanKind.CONSUMER)
            .setAttribute("messaging.system", "redis")
            .setAttribute("messaging.operation", "process")
            .setAttribute("messaging.destination.name", "emails")
            .setAttribute("code.function", "EmailWorker.processEmail")
            .startSpan();
        try (Scope scope = span.makeCurrent()) {
            sendEmail(job);
            span.setStatus(StatusCode.OK);
        } catch (Exception e) {
            span.recordException(e);
            span.setStatus(StatusCode.ERROR);
            throw e;
        } finally {
            span.end();
        }
    }
}

For one-shot Spring Boot CLI runs, the OpenTelemetry Java agent flushes pending spans in a JVM shutdown hook. SpringApplication.exit(...) and System.exit(0) both run this hook. Runtime.halt() and kill -9 do not, so the last spans are lost.

Next Steps


Explore the Spring Boot SDK