Package io.opentelemetry.common.impl

Class ApiUsageLogger

java.lang.Object

io.opentelemetry.common.impl.ApiUsageLogger

public final class ApiUsageLogger
extends Object

A utility for logging API misuse, allowing operators to diagnose invalid usage with a single logging configuration entry.

Logs at Level.FINEST by default, so messages are silent in production unless explicitly enabled. Each log record includes a Throwable to make the offending call site visible in the stack trace without requiring the exception to be thrown.

The first time any API misuse is detected, a one-time Level.WARNING is emitted to the io.opentelemetry.usage logger. This warning is visible under default logging configuration and signals that API misuse is occurring. To see the full details of every misuse event (message and stack trace), configure the io.opentelemetry.usage logger at Level.FINEST.

This class is not intended for use by application developers. Its API is stable and will not be changed or removed in a backwards-incompatible manner.

Since:

1.62.0

Method Summary

Modifier and Type	Method	Description
static void	logNullParam(Class<?> apiClass, String methodName, String paramName)	Log that paramName was null in apiClass#methodName.
static void	logUsageIssue(Class<?> apiClass, String methodName, String message)	Log a misuse of apiClass#methodName with the given message.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

logNullParam

public static void logNullParam(Class<?> apiClass,
 String methodName,
 String paramName)

Log that paramName was null in apiClass#methodName.

Convenience overload of logUsageIssue(Class, String, String) for the common case of a null parameter that should not be null.

Parameters:

apiClass - the public API class where the misuse occurred

methodName - the name of the method where the misuse occurred

paramName - the name of the parameter that was null

logUsageIssue

public static void logUsageIssue(Class<?> apiClass,
 String methodName,
 String message)

Log a misuse of apiClass#methodName with the given message.

Logs at Level.FINEST and includes a stack trace.

Parameters:

apiClass - the public API class where the misuse occurred

methodName - the name of the method where the misuse occurred

message - a brief description of the problem