Instrument with ActiveSupport::Notifications

[wagenet]

Since Grape already requires ActiveSupport, adding a couple of instrumentation points with ActiveSupport::Notifications requires minimal changes.

I did have to make some small changes to run_filters to provide "by type" instrumentation. However, the second parameter is optional so nothing bad should happen if other gems override this method with the old signature. In the worst case, all filters would report as being of type "other" or just not get reported at all.

About ActiveSupport::Notifications

AS::N is intended to be a generic instrumenter for Ruby applications and is very light-weight. It provides a great way for library authors to allow other tools (e.g. Skylight, NewRelic) to instrument the library in intelligent ways without having to monkeypatch. When nothing is observing a specific instrumentation the code is essentially a pass-through adding negligible overhead.

For more information see the documentation.

To Do

• Document the instrumentation points (in the vein of http://edgeguides.rubyonrails.org/active_support_instrumentation.html)
• Maybe write some tests to ensure that the instrumentation gives us what we expect.

[wagenet]

@dblock we discussed this a bit and I figured I'd just send in something simple to show the sort of thing I have in mind. The specific hook points I picked here are ones that I believe would be useful for Skylight, though again I believe they would be useful elsewhere. If we're not able to get first class support for these hooks, we'll have to resort to monkey patching.

[wagenet]

To expand further, I don't see how we could get this level of hooking with just a gem. The gem would also have to monkeypatch to get to the depths that these methods do. Alternatively, we could try splitting up the existing Grape methods more to allow for a relatively straight-forward alias + override flow. IMO, the minimal weight of instrumentation merits support in Grape itself, but this isn't my project :)

[dblock]

I'll leave this open for comments. I would prefer some refactoring in Grape where methods that make calls are more explicit and a separate gem that patches or overrides them. But I'd like others to comment.

[dblock]

This needs README documentation for sure if it were to get merged, you should write that and squash the commits.

[wagenet]

@dblock I'm definitely happy to add a README, tests, and anything else necessary. I just didn't want to spend too much time on something that was going to be dead on arrival.

[wagenet]

@dblock Are there any specific rules on when method signatures are changed? I know Grape hasn't reached 1.0 yet, but is the plan to be semver? Would this apply to all public class methods? documented methods? something else?

If we don't do this as a first class thing and instead override methods, I'd feel a lot more comfortable if I knew that API wouldn't change out from under me until a major release.

[dblock]

We don't have hard rules. I think it's definitely possible that the API would change underneath you, but the way I've done this in the past was to have a good battery of tests against specific versions of the upstream library, and make dependent gems compatible with a fixed number of releases. At the very least if there's an explicit method like run that does 1 thing it's unlikely that it will change.

So rough consensus and working code.

[wagenet]

@dblock I realized that Grape already requires ActiveSupport so I updated this PR to just use AS::N directly. This actually makes the code simpler than what I was originally proposing. I've updated the description accordingly.

[tchak]

This PR looks very useful. I hope it will be merged. Instrumentation should be first class citizen in any framework :)

[dblock]

Lets refactor the body into a method? Maybe run should call instrumented_run or run_instrumented (as in run_filters) something like that?

[wagenet]

@dblock I guess I'm confused as to how this helps. The implication here is that there could also be a run without instrumentation. What value does this provide?

[dblock]

Only some code clarity, shorter methods, easier to grok. No strong opinions.

[wagenet]

Fair enough, looks like the whole run method has potential for splitting up further.

[wagenet]

On further thought, refactoring seems good for a different PR.

[dblock]

I'd like to see a README for this and tests. I am open to this being part of Grape.

[wagenet]

@dblock I'll add some docs for this shortly.

[wagenet]

@dblock docs added and CHANGELOG updated. I'm still happy to clean up the run method a bit, but as I mentioned elsewhere I feel like that should be a separate PR.

[dblock]

There's a TOC above, I think this needs to be added there.

[wagenet]

Done.

[dblock]

Agreed re: run and a separate PR.

[dblock]

I thought about this more. If you write tests I will merge this.

[wagenet]

@dblock sounds great! I'll try to get the tests done today.

[wagenet]

@dblock I've added tests. They're a little unusual so if have suggestions for improving them, let me know.

[dblock]

Typo: subscriBe.

[dblock]

Fixed typo and merged via 94f52e4. Thank you.

[wagenet]

@dblock thanks!