Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

NH-90184: add doc for add_tracer api call #174

Merged
merged 11 commits into from
Jan 8, 2025
Merged
Show file tree
Hide file tree
Changes from 2 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 37 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -64,9 +64,11 @@ Note that if `OpenTelemetry::SDK.configure` is used to set up a `TracerProvider`

Several convenience and vendor-specific APIs are availabe to an application where `solarwinds_apm` has been loaded, below is a quick overview of the features provided. The full reference can be found at the [RubyDoc page for this gem](https://rubydoc.info/github/solarwinds/apm-ruby).

#### Convenience Method for in_span
#### Convenience Method: `in_span` and `add_tracer`

This method acquires the correct `Tracer` so a new span can be created in a single call, below is a simple Rails controller example:
`in_span` acquires the correct `Tracer` so a new span can be created in a single call.

For example, below is a simple Rails controller
xuan-cao-swi marked this conversation as resolved.
Show resolved Hide resolved

```ruby
class StaticController < ApplicationController
Expand All @@ -78,6 +80,39 @@ class StaticController < ApplicationController
end
```

`add_tracer` can add a custom span to the specified instance or class method that is already defined. `add_tracer` allow to set custom span name, span kind and additional attributes in hash format
xuan-cao-swi marked this conversation as resolved.
Show resolved Hide resolved

```ruby
add_tracer :function_name, 'custom_span_name', { attributes: { 'any' => 'attributes' }, kind: :span_kind }
xuan-cao-swi marked this conversation as resolved.
Show resolved Hide resolved
```

For example, if you want to instrument class function or instance function `create_session` inside application controller
xuan-cao-swi marked this conversation as resolved.
Show resolved Hide resolved

```ruby
class SessionsController < ApplicationController
include SolarWindsAPM::API::Tracer

def create
user = User.find_by(email: params[:session][:email].downcase)
create_session(user)
end

# instrument class function create_session
def create_session(user)
end
add_tracer :create_session, 'custom_name', { attributes: { 'foo' => 'bar' }, kind: :consumer }

# instrument instance function self.create_session
def self.create_session(user)
end

class << self
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
# instrument class function create_session
def create_session(user)
end
add_tracer :create_session, 'custom_name', { attributes: { 'foo' => 'bar' }, kind: :consumer }
# instrument instance function self.create_session
def self.create_session(user)
end
class << self
def create_session(user)
end
def self.create_session(user)
end
# instrument instance method create_session
add_tracer :create_session, 'custom_name', { attributes: { 'foo' => 'bar' }, kind: :consumer }
# instrument class method create_session
class << self

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think create_session is the instance method, while self.create_session is the class method. And is the include SolarWindsAPM::API::Tracer on line 93 needed by the "instrument instance method" usage? It might be clearer if we just show the instrument instance vs class method as two separate snippets.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do you mean like putting them in separate code block?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also, how about the docstring

Updated

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, i mean two separate code blocks, because currently it's unclear where include SolarWindsAPM::API::Tracer is needed for each scenario--the current example has it once at the start of class definition, then again via the class << self construct. If we keep a single code block example it would be good to clarify why.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Updated

include SolarWindsAPM::API::Tracer
add_tracer :create_session, 'custom_name', { attributes: { 'foo' => 'bar' }, kind: :consumer }
end
end
```

#### Get Curent Trace Context Information

The `current_trace_info` method returns a `TraceInfo` object containing string representations of the current trace context that can be used in logging or manual propagation of context. This is a convenience method that wraps the OTel API `::OpenTelemetry::Trace.current_span`.
Expand Down
9 changes: 0 additions & 9 deletions gemfiles/rails_6x.gemfile

This file was deleted.

1 change: 0 additions & 1 deletion test/run_tests.sh
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,6 @@ check_status() {

gemfiles=(
"gemfiles/unit.gemfile"
"gemfiles/rails_6x.gemfile"
)

##
Expand Down
Loading