RFC: Instrumentation

[Matt Todd]

Not too long ago, I proposed a Pull Request to add some hooks into the Net::LDAP internals, starting first with low level operations, bytes over the wire, binds and new connections, and eventually scoped up to include higher level operations like bind, search, add, modify, delete, etc. The instrumentation API is compatible with ActiveSupport::Notifications, though it's off by default and can can work with any object with a similar API.

The PR was merged and released as part of 0.8.0! Check it out here:

https://github.com/ruby-ldap/ruby-net-ldap/pull/101

The motivation for this addition was to make it easier to gain some visibility into the runtime operations to expose inefficiencies, provide clarity on what's happening at the lower level in support of a higher level operation, etc; in short, logging and tuning.

Here's a simplistic example:

# setup
auth    = {...}
options = {...}
options[:instrumentation_service] = ActiveSupport::Notifications

ldap = Net::LDAP.new(options)

# subscribe to an event
ActiveSupport::Notifications.subscribe "bind.net_ldap_connection" do |name, start, finish, id, payload|
  p ["bind", payload[:result]]
end

# perform operation that triggers event
ldap.bind(auth)
# prints: ["bind", true]

I plan to continue improving the instrumentation of the library, at all levels, and to provide better context for each event, as well as proper documentation once more of these details have been worked out. What I'd love is some feedback on what kind of visibility is desired into these events (what's missing from the payload), what else makes sense to instrument (PDU parsing? BER encoding? et al), and what needs you have that instrumentation can help address, particularly if it's not able to do that now (as of 0.8.0).

Thoughts? Needs? Wants? Would love feedback on this!

Cheers,

Matt

[Matt Todd]

One thing I'd like to expose more is the response/result from the server, any time there's an operation result emit an event, and include it in any relevant event payload, too.