Package org.apache.camel.spi

Interface BacklogDebugger

All Superinterfaces:
AutoCloseable, Service, ShutdownableService, StatefulService, SuspendableService
public interface BacklogDebugger extends StatefulService
A Debugger that has easy debugging functionality which can be used from JMX with
invalid reference 
org.apache.camel.api.management.mbean.ManagedBacklogDebuggerMBean
.

This implementation allows setting breakpoints (with or without a condition) and inspect the Exchange dumped in XML in BacklogTracerEventMessage format. There is operations to resume suspended breakpoints to continue routing the Exchange. There is also step functionality, so you can single step a given Exchange.

This implementation will only break the first Exchange that arrives to a breakpoint. If Camel routes using concurrency then sub-sequent Exchange will continue to be routed, if their breakpoint already holds a suspended Exchange.

  • 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

      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

      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

      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

      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