Interface BacklogDebugger

All Superinterfaces:
AutoCloseable, Service, ShutdownableService, StatefulService, SuspendableService
public interface BacklogDebugger extends StatefulService
High-level route debugger SPI that suspends Exchange processing at named breakpoints and exposes the suspended state for inspection, as described in the Debugger documentation.

The BacklogDebugger builds on the lower-level Debugger API but adds breakpoint management with optional conditions, step-mode execution, and exchange inspection via XML/JSON dumps in BacklogTracerEventMessage format. All operations are exposed over JMX through

invalid reference 
org.apache.camel.api.management.mbean.ManagedBacklogDebuggerMBean
, allowing IDE tooling (e.g., camel-idea-plugin) to control a running Camel context remotely.

On reaching a breakpoint, only the first arriving Exchange is suspended; concurrent exchanges on the same breakpoint continue to route past it. A suspended exchange blocks its carrier thread until explicitly resumed via one of the resume* methods.

When the environment variable "CAMEL_DEBUGGER_SUSPEND" (or system property "org.apache.camel.debugger.suspend") is set to true, the debugger suspends all routes at startup and waits for a debugger client to attach before processing any messages.

Since:
4.2
See Also:

  • Field Details

    • SUSPEND_MODE_ENV_VAR_NAME

      static final String SUSPEND_MODE_ENV_VAR_NAME
      The name of the OS environment variable that contains the value of the flag indicating whether the BacklogDebugger should suspend processing the messages and wait for a debugger to attach or not.
      See Also:

    • SUSPEND_MODE_SYSTEM_PROP_NAME

      static final String SUSPEND_MODE_SYSTEM_PROP_NAME
      The name of the system property that contains the value of the flag indicating whether the BacklogDebugger should suspend processing the messages and wait for a debugger to attach or not.
      See Also:

    • BREAKPOINT_ALL_ROUTES

      static final String BREAKPOINT_ALL_ROUTES
      Special breakpoint id token to automatically add breakpoint for every route.
      See Also:

  • Method Details

    • getInitialBreakpoints

      @Nullable String getInitialBreakpoints()
      Allows to pre-configure breakpoints (node ids) to use with debugger on startup. Multiple ids can be separated by comma. Use special value _all_routes_ to add a breakpoint for the first node for every route, in other words this makes it easy to debug from the beginning of every route without knowing the exact node ids.

    • setInitialBreakpoints

      void setInitialBreakpoints(String initialBreakpoints)
      Allows to pre-configure breakpoints (node ids) to use with debugger on startup. Multiple ids can be separated by comma. Use special value _all_routes_ to add a breakpoint for the first node for every route, in other words this makes it easy to debug from the beginning of every route without knowing the exact node ids.

    • getLoggingLevel

      String getLoggingLevel()
      The debugger logging level to use when logging activity.

    • setLoggingLevel

      void setLoggingLevel(String level)
      The debugger logging level to use when logging activity.

    • enableDebugger

      void enableDebugger()
      To enable and start the debugger

    • disableDebugger

      void disableDebugger()
      To disable and stop the debugger

    • setEnabled

      void setEnabled(boolean enabled)
      To configure whether the debugger should be enabled

    • isEnabled

      boolean isEnabled()
      Whether the debugger is enabled

    • isStandby

      boolean isStandby()
      Whether the debugger is standby.

      If a debugger is in standby then the tracer is activated during startup and are ready to be enabled manually via JMX or calling the enableDebugger method.

    • setStandby

      void setStandby(boolean standby)
      Whether the debugger is standby.

      If a debugger is in standby then the tracer is activated during startup and are ready to be enabled manually via JMX or calling the enableDebugger method.

    • hasBreakpoint

      boolean hasBreakpoint(String nodeId)
      Does the node have a breakpoint

    • setSuspendMode

      void setSuspendMode(boolean suspendMode)
      Whether the debugger should suspend on startup, and wait for a remote debugger to attach. This is what the IDEA and VSCode tooling is using.

    • isSuspendMode

      boolean isSuspendMode()
      Whether the debugger should suspend on startup, and wait for a remote debugger to attach. This is what the IDEA and VSCode tooling is using.

    • isSingleStepMode

      boolean isSingleStepMode()
      Is the debugger currently in single step mode

    • attach

      void attach()
      Attach the debugger which will resume the message processing in case the suspend mode is enabled. Do nothing otherwise.

    • detach

      void detach()
      Detach the debugger which will suspend the message processing in case the suspend mode is enabled. Do nothing otherwise.

    • addBreakpoint

      void addBreakpoint(String nodeId)
      Adds a breakpoint for the given node

    • addConditionalBreakpoint

      void addConditionalBreakpoint(String nodeId, String language, String predicate)
      Adds a conditional breakpoint for the given node

    • removeBreakpoint

      void removeBreakpoint(String nodeId)
      Removes the breakpoint

    • removeAllBreakpoints

      void removeAllBreakpoints()
      Remove all breakpoints

    • getBreakpoints

      Set<String> getBreakpoints()
      Gets all the breakpoint (node ids)

    • resumeBreakpoint

      void resumeBreakpoint(String nodeId)
      Resume the breakpoint

    • resumeBreakpoint

      void resumeBreakpoint(String nodeId, boolean stepMode)
      Resume the breakpoint in step mode

    • setMessageBodyOnBreakpoint

      void setMessageBodyOnBreakpoint(String nodeId, Object body)
      Updates the message body at the given breakpoint

    • setMessageBodyOnBreakpoint

      void setMessageBodyOnBreakpoint(String nodeId, Object body, Class<?> type)
      Updates the message body at the given breakpoint

    • removeMessageBodyOnBreakpoint

      void removeMessageBodyOnBreakpoint(String nodeId)
      Removes the message body (set as null) at the given breakpoint

    • setMessageHeaderOnBreakpoint

      void setMessageHeaderOnBreakpoint(String nodeId, String headerName, Object value) throws NoTypeConversionAvailableException
      Sets the message header at the given breakpoint
      Throws:
      NoTypeConversionAvailableException

    • setMessageHeaderOnBreakpoint

      void setMessageHeaderOnBreakpoint(String nodeId, String headerName, Object value, Class<?> type) throws NoTypeConversionAvailableException
      Sets the message header at the given breakpoint
      Throws:
      NoTypeConversionAvailableException

    • setExchangePropertyOnBreakpoint

      void setExchangePropertyOnBreakpoint(String nodeId, String exchangePropertyName, Object value) throws NoTypeConversionAvailableException
      Sets the exchange property at the given breakpoint
      Throws:
      NoTypeConversionAvailableException

    • setExchangePropertyOnBreakpoint

      void setExchangePropertyOnBreakpoint(String nodeId, String exchangePropertyName, Object value, Class<?> type) throws NoTypeConversionAvailableException
      Updates the exchange property at the given breakpoint
      Throws:
      NoTypeConversionAvailableException

    • removeMessageHeaderOnBreakpoint

      void removeMessageHeaderOnBreakpoint(String nodeId, String headerName)
      Removes the message header at the given breakpoint

    • removeExchangePropertyOnBreakpoint

      void removeExchangePropertyOnBreakpoint(String nodeId, String exchangePropertyName)
      Removes the exchange property at the given breakpoint

    • setExchangeVariableOnBreakpoint

      void setExchangeVariableOnBreakpoint(String nodeId, String variableName, Object value) throws NoTypeConversionAvailableException
      Updates/adds the variable (uses same type as old variableName value) on the suspended breakpoint at the given node id
      Throws:
      NoTypeConversionAvailableException

    • setExchangeVariableOnBreakpoint

      void setExchangeVariableOnBreakpoint(String nodeId, String variableName, Object value, Class<?> type) throws NoTypeConversionAvailableException
      Updates/adds the variable (with a new type) on the suspended breakpoint at the given node id
      Throws:
      NoTypeConversionAvailableException

    • removeExchangeVariableOnBreakpoint

      void removeExchangeVariableOnBreakpoint(String nodeId, String variableName)
      Removes the variable on the suspended breakpoint at the given node id

    • getFallbackTimeout

      long getFallbackTimeout()
      Fallback Timeout in seconds (300 seconds as default) when block the message processing in Camel. A timeout used for waiting for a message to arrive at a given breakpoint.

    • setFallbackTimeout

      void setFallbackTimeout(long fallbackTimeout)
      Fallback Timeout in seconds (300 seconds as default) when block the message processing in Camel. A timeout used for waiting for a message to arrive at a given breakpoint.

    • resumeAll

      void resumeAll()
      To resume all suspended breakpoints.

    • stepBreakpoint

      void stepBreakpoint(String nodeId)
      To start single step mode from a suspended breakpoint at the given node. Then invoke step() to step to next node in the route.

    • stepBreakpoint

      void stepBreakpoint()
      To start single step mode from the current suspended breakpoint. Then invoke step() to step to next node in the route.

    • step

      void step()
      To step (into) to next node when in single step mode.

    • stepOver

      void stepOver()
      To step over to next node when in single step mode.

    • skipOver

      void skipOver()
      To skip over (does not call the node) to next node when in single step mode.

    • getSuspendedBreakpointNodeIds

      Set<String> getSuspendedBreakpointNodeIds()
      Gets node ids for all current suspended exchanges at breakpoints

    • getSuspendedExchangeIds

      Set<String> getSuspendedExchangeIds()
      Gets the exchange ids for all current suspended exchanges

    • getSuspendedExchange

      @Nullable Exchange getSuspendedExchange(String id)
      Gets the exchanged suspended at the given breakpoint id or null if there is none at that id.
      Parameters:
      id - node id for the breakpoint
      Returns:
      the suspended exchange or null if there isn't one suspended at the given breakpoint.

    • getSuspendedBreakpointMessage

      @Nullable BacklogTracerEventMessage getSuspendedBreakpointMessage(String id)
      Gets the trace event for the suspended exchange at the given breakpoint id or null if there is none at that id.
      Parameters:
      id - node id for the breakpoint
      Returns:
      the trace event or null if there isn't one suspended at the given breakpoint.

    • disableBreakpoint

      void disableBreakpoint(String nodeId)
      Disables a breakpoint

    • enableBreakpoint

      void enableBreakpoint(String nodeId)
      Enables a breakpoint

    • setSingleStepIncludeStartEnd

      void setSingleStepIncludeStartEnd(boolean singleStepIncludeStartEnd)
      In single step mode, then when the exchange is created and completed, then simulate a breakpoint at start and end, that allows to suspend and watch the incoming/complete exchange at the route (you can see message body as response, failed exception etc).

    • isSingleStepIncludeStartEnd

      boolean isSingleStepIncludeStartEnd()
      In single step mode, then when the exchange is created and completed, then simulate a breakpoint at start and end, that allows to suspend and watch the incoming/complete exchange at the route (you can see message body as response, failed exception etc).

    • getBodyMaxChars

      int getBodyMaxChars()
      To limit the message body to a maximum size in the traced message. Use 0 or negative value to use unlimited size.

    • setBodyMaxChars

      void setBodyMaxChars(int bodyMaxChars)
      To limit the message body to a maximum size in the traced message. Use 0 or negative value to use unlimited size.

    • isBodyIncludeStreams

      boolean isBodyIncludeStreams()
      Whether to include the message body of stream based messages. If enabled then beware the stream may not be re-readable later. See more about Stream Caching.

    • setBodyIncludeStreams

      void setBodyIncludeStreams(boolean bodyIncludeStreams)
      Whether to include the message body of stream based messages. If enabled then beware the stream may not be re-readable later. See more about Stream Caching.

    • isBodyIncludeFiles

      boolean isBodyIncludeFiles()
      Whether to include the message body of file based messages. The overhead is that the file content has to be read from the file.

    • setBodyIncludeFiles

      void setBodyIncludeFiles(boolean bodyIncludeFiles)
      Whether to include the message body of file based messages. The overhead is that the file content has to be read from the file.

    • isIncludeExchangeProperties

      boolean isIncludeExchangeProperties()
      Whether to include the exchange properties in the traced message

    • setIncludeExchangeProperties

      void setIncludeExchangeProperties(boolean includeExchangeProperties)
      Whether to include the exchange properties in the traced message

    • isIncludeExchangeVariables

      boolean isIncludeExchangeVariables()
      Whether to include the exchange variables in the traced message

    • setIncludeExchangeVariables

      void setIncludeExchangeVariables(boolean includeExchangeVariables)
      Whether to include the exchange variables in the traced message

    • isIncludeException

      boolean isIncludeException()
      Trace messages to include exception if the message failed

    • setIncludeException

      void setIncludeException(boolean includeException)
      Trace messages to include exception if the message failed

    • dumpTracedMessagesAsXml

      String dumpTracedMessagesAsXml(String nodeId)
      To dump the debugged messages from the give node id in XML format.

    • dumpTracedMessagesAsJSon

      String dumpTracedMessagesAsJSon(String nodeId)
      To dump the debugged messages from the give node id in JSon format.

    • getDebugCounter

      long getDebugCounter()
      Number of breakpoint that has been hit

    • resetDebugCounter

      void resetDebugCounter()
      Rests the debug counter

    • beforeProcess

      @Nullable org.apache.camel.util.StopWatch beforeProcess(Exchange exchange, Processor processor, NamedNode definition)
      Callback invoked before hitting a breakpoint

    • afterProcess

      void afterProcess(Exchange exchange, Processor processor, NamedNode definition, long timeTaken)
      Callback invoked after a breakpoint