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:
-
redactHeaders: A list of HTTP header keys. -
redactRequestBody: A list of JSONPaths from the request body. -
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.redactHeadersproperty expects a list of case-insensitive headers as strings. - The
apitoolkit.redactRequestBodyandapitoolkit.redactResponseBodyproperties 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
- Send a few requests to your application. Then open Log Explorer in monoscope to see the requests, logs and traces.
- Find your way around the dashboard: issues, monitors, dashboards and the API catalog.
- Investigate from your terminal or your agent with the CLI, the skills and the MCP server.
Explore the Spring Boot SDK