# API

## Store Exception

To record exceptions handled by a try-catch block, use `RevDeBugAPI.Snapshot.RecordException` and pass the exception object as a parameter. For example:

```java
try{
    var product = new Product();
    product.convertData(dataFile);
}
catch (Exception e){
    RevDeBug.Storage.getStorageApi().StoreException(error, CatchStateType.EXCEPTION);
}
```

The recorded snapshot of code execution that led to the exception will be stored on a Recording Server and visible on the RevDeBug DevOps Monitoring dashboard in the same manner unhandled exceptions are. 

To use a store exception, you must provide the exception object to be recorded by RevDeBug as arguments of the StoreException function and select one of the two exception types as the second argument: 

* `CatchStateType.EXCEPTION` - This is the normal type of exception 
* `CatchStateType.LOG_ERROR` - the exception will be marked in the exception table as a log error

```java
RevDeBug.Storage.getStorageApi().StoreException(exception_object, CatchStateType.LOG_ERROR);

RevDeBug.Storage.getStorageApi().StoreException(new Exception(), CatchStateType.EXCEPTION);
```

## Store Snapshot

RevDeBug offers the possibility to create code recordings even when there is no exception. To use the function you should call the function anywhere in the program code. The place in the code where we used the snapshot function will be the end of the recording.

```java
RevDeBug.Storage.getStorageApi().StoreSnapshot("Code segment execution");
```

## Enable/Disable Recording From API

You can deactivate and activate the RevDeBug flight recorder at any time from the API. 

To deactivate the flight recorder:

```java
RevDeBug.Storage.getStorageApi().Deactivate();
```

To activate the flight recorder:

```java
RevDeBug.Storage.getStorageApi().Activate();
```

To check if RevDeBug flight recorder is running or not:

```java
RevDeBug.Storage.getStorageApi().IsActive()
```

## Clear Thread Data

If you do not want to record a section of the code, all you have to do is use the `ClearThreadData()` function in the code, which will erase the current recording buffer. The code recording will start over from where `ClearThreadData()` is used.

```java
RevDeBug.Storage.getStorageApi().ClearThreadData();
```

## Set Maximum Recording Length

You can set the maximum length of the recording (the default is 1000). To do this via api use:

```java
RevDeBug.Storage.getStorageApi().SetRecordingBacklog(1000);
```

The length of the recording is the number of application states that will be recorded, such as: variable values, values returned by methods, etc.

## Trace ID in logs

In Java Agent if you want to get the trace ID in the logs of your application then you need to add the following dependency to pom.xml:

{% code title="pom.xml" overflow="wrap" %}

```xml
<project>
    ...
    <dependencies>
         <dependency>
            <groupId>com.revdebug</groupId>
            <artifactId>apm-toolkit-logback-1.x</artifactId>
            <version>8.8.0</version>
         </dependency>
    ...
</project>
```

{% endcode %}

In the logback.xml file, which is a sample file and contains the log template, you must add the layout with a specific class `org.apache.skywalking.apm.toolkit.log.logback.v1.x.mdc.TraceIdMDCPatternLogbackLayout` and pattern with `[%X{tid}]` . Sample implementation here:

{% code title="logback.xml" %}

```xml
<configuration>
    <appender name="console" class="ch.qos.logback.core.ConsoleAppender">
        <encoder class="ch.qos.logback.core.encoder.LayoutWrappingEncoder">
            <layout class="org.apache.skywalking.apm.toolkit.log.logback.v1.x.mdc.TraceIdMDCPatternLogbackLayout">
                <Pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%X{tid}] [%thread] %-5level %logger{36} -%msg%n</Pattern>
            </layout>
        </encoder>
    </appender>

    <root level="info">
        <appender-ref ref="console"/>
    </root>
</configuration>
```

{% endcode %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://revdebug.gitbook.io/revdebug/supported-langauges/java/api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.