feat: add net_ldap instrumentation #1587

scbjans · 2025-07-09T12:08:10Z

Largely based on prior work in #1432 by @Hareramrai and @jdehaan

Since that PR seems stale, I've updated it with some small edits to comply with release management using toys.

Should fix: github.com//issues/669

.toys/.data/releases.yml

instrumentation/net_ldap/lib/opentelemetry/instrumentation/net/ldap/instrumentation.rb

arielvalentin · 2025-07-09T12:43:30Z

instrumentation/net_ldap/lib/opentelemetry/instrumentation/net/ldap/instrumentation_service.rb

+              yield(payload).tap do |response|
+                annotate_span_with_response!(span, response)
+              end
+            rescue StandardError => e


Doesn't in_span already handle Error Recording and setting the status?

Yes it does, but it doesn't add the ldap.error_message attribute. I've updated this a bit, and in 0583992 we'll rescue specifically on a ::Net::LDAP::Error

arielvalentin · 2025-07-09T12:44:39Z

instrumentation/net_ldap/lib/opentelemetry/instrumentation/net/ldap/instrumentation_service.rb

+            LDAP::Instrumentation.instance.config
+          end
+
+          def annotate_span_with_response!(span, response)


Only add a ! if you have an existing method that does not have a !

arielvalentin · 2025-07-09T12:47:20Z

instrumentation/net_ldap/lib/opentelemetry/instrumentation/net/ldap/instrumentation_service.rb

+
+            return if ::Net::LDAP::ResultCodesNonError.include?(status_code)
+
+            span.record_exception(error_message) unless error_message.empty?


I believe record_exception is an explicit helper for exception events. Consider using the Span Status Code description instead.

arielvalentin · 2025-07-09T12:58:19Z

release-please-config.json

    }
  }
-}
+}


Suggested change

}

}

arielvalentin · 2025-07-09T13:10:03Z

instrumentation/net_ldap/lib/opentelemetry/instrumentation/net/ldap/instrumentation_service.rb

+              OpenTelemetry::SemanticConventions::Trace::NET_PEER_NAME => host || hosts,
+              OpenTelemetry::SemanticConventions::Trace::NET_PEER_PORT => port,
+              OpenTelemetry::SemanticConventions::Trace::PEER_SERVICE => instrumentation_config[:peer_service]
+            }.merge!(OpenTelemetry::Common::HTTP::ClientContext.attributes)


why is this amending HTTP Client attributes? How is that relevant to LDAP lookups?

TBH I just took the already existing stale PR that originally was opened to add this instrumentation. That did the job for me, and I thought it might be beneficial for others to have this instrumentation more easily available.
I rushed this a bit and skipped the due diligence (sorry!), so I'm glad you ask.

It doesn't: I removed it.

arielvalentin · 2025-07-09T13:12:45Z

instrumentation/net_ldap/lib/opentelemetry/instrumentation/net/ldap/instrumentation_service.rb

+            @encryption = args[:encryption]
+          end
+
+          def instrument(event, payload)


Do we want more specific attribute mappers here for each of these events?

https://github.com/search?q=repo%3Aruby-ldap%2Fruby-net-ldap+%2Finstrument+%22%2F&type=code

I do not particularly like the practice of dumping json strings where we do not know if the contents of the provided payload have sensitive information in them.

I agree.

My naive thought was that it would be handled in net-ldap itself, but upon closer inspection I see that this instrumentation can leak e.g. passwords in cleartext.
I'll need some time to figure out which specific attributes to include.

Fixed and added test in 3d2ff26

I think a good starting point would be to capture the name of the operation being performed ie open, read, parse_pdu.

arielvalentin · 2025-07-09T13:16:59Z

instrumentation/net_ldap/lib/opentelemetry/instrumentation/net/ldap/instrumentation_service.rb

+
+            tracer.in_span(
+              event,
+              attributes: attributes.compact,


This allocates and extra hash object.

lets avoid that by checking if the values are present before adding them to the hash.

arielvalentin · 2025-07-09T13:18:50Z

instrumentation/net_ldap/lib/opentelemetry/instrumentation/net/ldap/instrumentation_service.rb

+            tracer.in_span(
+              event,
+              attributes: attributes.compact,
+              kind: :client


Do you think LDAP qualifies as RPC? Would using RPC client semantics be right for this?
Would using ECS style events make more sense for these?

I was inclined to say LDAP qualifies as RPC, but my AI friend does not agree with me. Apparently LDAP itself is not RPC, but it is often combined with RPC (e.g. when joining computers to Windows domains), but we're only instrumenting LDAP in this case. Semconv doesn't specify anything for ldap, and other languages don't seem to have ldap instrumentation.

I'm not sure what to do here.

Good points. I was also wondering about SemConv as I'm reading through this. I asked the #opentelemetry-semantic-conventions channel on CNCF Slack for advice.

Heard back from the thread. There aren't any specific LDAP conventions we should adhere to. Instead, they suggested we use attributes from other relevant categories like network and server.

arielvalentin · 2025-07-09T16:17:50Z

instrumentation/net_ldap/lib/opentelemetry/instrumentation/net/ldap/patches/instrumentation.rb

+            def initialize(args = {})
+              super
+
+              @instrumentation_service = args[:instrumentation_service] || OpenTelemetry::Instrumentation::Net::LDAP::InstrumentationService.new({


Another thought I have here, what if we added this otel instrumentation as a decorator to the injected service?

kaylareopelle

Hi @scbjans, thanks for opening this PR.

I'm not very familiar with LDAP, so I'll take another pass once I learn a bit more. For now, I left a few comments.

In addition to those comments, would you mind updating the CODEOWNERS file to list you as the owner of this gem? PR assignment for CODEOWNERS is currently broken, but I'm hoping to get it fixed soon.

kaylareopelle · 2025-09-16T23:52:59Z

instrumentation/net_ldap/example/Gemfile

+gem 'opentelemetry-api'
+gem 'opentelemetry-common'
+gem 'opentelemetry-instrumentation-base'


should be able to leave these out, since they're dependencies of the other gems.

Suggested change

gem 'opentelemetry-api'

gem 'opentelemetry-common'

gem 'opentelemetry-instrumentation-base'

kaylareopelle · 2025-09-17T00:04:20Z

instrumentation/net_ldap/lib/opentelemetry/instrumentation/net/ldap/instrumentation_service.rb

+            tracer.in_span(
+              event,
+              attributes: attributes.compact,
+              kind: :client


Good points. I was also wondering about SemConv as I'm reading through this. I asked the #opentelemetry-semantic-conventions channel on CNCF Slack for advice.

instrumentation/net_ldap/lib/opentelemetry/instrumentation/net/ldap/instrumentation_service.rb

thompson-tomo · 2025-09-17T07:13:36Z

instrumentation/net_ldap/lib/opentelemetry/instrumentation/net/ldap/instrumentation_service.rb

+
+          def instrument(event, payload)
+            attributes = {
+              'ldap.auth' => auth.except(:password).to_json,


Do we need auth given we removed it from db etc?

I'm not sure why it was removed from db, but I think it's valuable to see which user connects to ldap; e.g. to troubleshoot permissions

I believe it was in relation to the range of different auth methods/mechanism that could be used ie certificates vs user credentials.

The name Auth doesn't feel scoped enough as it could mean many things. In ldap v3 SASL is supported which opens up additional techniques.

instrumentation/net_ldap/lib/opentelemetry/instrumentation/net/ldap/instrumentation_service.rb

…ile.

scbjans · 2025-09-17T09:57:41Z

@kaylareopelle thanks for your feedback; I updated it in 7264acb

@thompson-tomo thank you as well for your feedback, I believe I addressed it in 44a1d54
However, tests are failing, because the new opentelemetry-semantic_conventions is missing some requires of the SemConv module. I'll have to tidy up my fixes for that and submit a PR

instrumentation/net_ldap/lib/opentelemetry/instrumentation/net/ldap/instrumentation_service.rb

thompson-tomo · 2025-09-18T03:03:15Z

instrumentation/net_ldap/lib/opentelemetry/instrumentation/net/ldap/instrumentation_service.rb

+          def instrument(event, payload)
+            attributes = {
+              'ldap.auth' => auth.except(:password).to_json,
+              'ldap.base' => base,


Should this become ldap.tree.base or similar that way we have potential of adding other properties for the tree.

thompson-tomo · 2025-09-18T03:08:52Z

instrumentation/net_ldap/lib/opentelemetry/instrumentation/net/ldap/instrumentation_service.rb

+            attributes = {
+              'ldap.auth' => auth.except(:password).to_json,
+              'ldap.base' => base,
+              'ldap.encryption' => encryption.to_json,


Not sure of the benefits of this given it could be a hash of properties.

feat: add net_ldap instrumentation

623e8f0

scbjans requested review from fbogsany, mwear, robertlaurin, dazuma, ericmustin, arielvalentin, ahayworth, plantfansam, robbkidd, simi, kaylareopelle, xuan-cao-swi and a team as code owners July 9, 2025 12:08

scbjans added 2 commits July 9, 2025 14:10

chore: instrumentation-net_ldap should not yet be included in all

addcd6d

chore: add missing appraisals

e147bbe

arielvalentin reviewed Jul 9, 2025

View reviewed changes

scbjans marked this pull request as draft July 9, 2025 14:30

arielvalentin reviewed Jul 9, 2025

View reviewed changes

scbjans added 5 commits July 11, 2025 10:11

chore: feedback

0583992

chore: add version constraint >=0.17.1 for net-ldap

cb5f1c4

fix: redact sensitive attributes

3d2ff26

fix: appease the cop

577fa5e

Merge branch 'main' into 669-add-net_ldap-instrumentation

ce29169

scbjans marked this pull request as ready for review August 18, 2025 12:12

scbjans requested a review from arielvalentin August 27, 2025 09:00

Merge branch 'main' into 669-add-net_ldap-instrumentation

bbd0770

kaylareopelle reviewed Sep 17, 2025

View reviewed changes

thompson-tomo reviewed Sep 17, 2025

View reviewed changes

scbjans added 2 commits September 17, 2025 10:43

chore: update CODEOWNERS, remove superfluous requires in example Gemf…

7264acb

…ile.

chore: update attribute names

44a1d54

chore: add missing requires

60ec2e7

scbjans commented Sep 17, 2025

View reviewed changes

instrumentation/net_ldap/lib/opentelemetry/instrumentation/net/ldap/instrumentation_service.rb Show resolved Hide resolved

chore: add test for peer.service

111f18c

thompson-tomo reviewed Sep 18, 2025

View reviewed changes


		return if ::Net::LDAP::ResultCodesNonError.include?(status_code)

		span.record_exception(error_message) unless error_message.empty?

	gem 'opentelemetry-api'
	gem 'opentelemetry-common'
	gem 'opentelemetry-instrumentation-base'

feat: add net_ldap instrumentation #1587

Are you sure you want to change the base?

feat: add net_ldap instrumentation #1587

Uh oh!

Conversation

scbjans commented Jul 9, 2025

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kaylareopelle left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

scbjans commented Sep 17, 2025

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!