Introduce Callback Functions for Constructor & Decorator Calls #377
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Recently folks have been asking for more visiblity into what constructors
and decorators actually get called, especially Fx users.
This implementation allows users to provide callback functions
for Dig to call when it invokes a constructor or decorator.
Dig will pass along info such as which function was actually called,
the name (package + name) of the function, and what kind it was
(provided or decorated), when it calls the provided callback function.
Users can provide a callback by using the new `dig.Option`, `dig.WithCallback`:
```go
type MyCallback struct {}
func (MyCallback) Called(ci dig.CallbackInfo) {
switch ci.Kind {
case dig.Provided:
fmt.Printf("My provided function %q was called!\n", ci.Name)
case dig.Decorated:
fmt.Printf("My decorator %q was called!\n", ci.Name)
}
}
func main() {
// ...
c := dig.New(WithCallback(MyCallback{}))
// ...
}
```
With this addition, from the Fx side, we can register a callback function
that will generate new Fx events when constructors and decorators get
called. This will help users identify which _do not_ get called, and thus
identify dead code.
Internal Ref: GO-1873
Codecov Report
@@ Coverage Diff @@
## master #377 +/- ##
==========================================
+ Coverage 98.35% 98.38% +0.03%
==========================================
Files 21 22 +1
Lines 1458 1490 +32
==========================================
+ Hits 1434 1466 +32
Misses 15 15
Partials 9 9
... and 1 file with indirect coverage changes 📣 We’re building smart automated test selection to slash your CI/CD build times. Learn more |
JacobOaks
changed the title
JacobOaks
changed the title
tchung1118
reviewed
Apr 19, 2023
manjari25
reviewed
Apr 21, 2023
manjari25
reviewed
Apr 21, 2023
manjari25
reviewed
Apr 21, 2023
manjari25
reviewed
Apr 21, 2023
callback.go
Outdated
Comment on lines
31
to
33
| // Error contains the error returned by the [Callback]'s associated | ||
| // function, if there was one. | ||
| Error error |
There was a problem hiding this comment.
It would be nice if we can allow differentiation between regular errors vs panic errors.
There was a problem hiding this comment.
Users should be able to do this using errors.As
https://pkg.go.dev/go.uber.org/dig#PanicError
manjari25
reviewed
Apr 21, 2023
sywhang
reviewed
May 1, 2023
tchung1118
approved these changes
May 1, 2023
sywhang
approved these changes
May 1, 2023
JacobOaks
added a commit
to uber-go/fx
that referenced
this pull request
May 15, 2023
Folks have been asking for additional observability into what constructors/decorators they give to Fx actually get invoked. With uber-go/dig#377 being merged, we can use Dig callbacks to provide this observability point. This PR does this by registering callbacks with Dig that generate a new [fxevent](https://pkg.go.dev/go.uber.org/fx/fxevent#Event) called `fxevent.Run`, containing information about the provided/decorated function that was invoked by Dig: ```go // Run is emitted after a constructor, decorator, or supply/replace stub is run by Fx. type Run struct { // Name is the name of the function that was run. Name string // Kind indicates which Fx option was used to pass along the function. // It is either "provide", "decorate", "supply", or "replace". Kind string // ModuleName is the name of the module in which the function belongs. ModuleName string // Err is non-nil if the function returned an error. // If fx.RecoverFromPanics is used, this will include panics. Err error } ``` The default [fxevent.Logger](https://pkg.go.dev/go.uber.org/fx/fxevent#Logger)s have been updated to print to the console/log with Zap accordingly. Folks can use custom `fxevent.Logger`s to respond to these events as they would any other event: ```go type myLogger struct{ /* ... */ } func (l *myLogger) LogEvent(event fxevent.Event) { switch e := event.(type) { // ... case *fxevent.Run: // can access e.Name, e.Kind, e.ModuleName, and e.Err // ... } } func main() { app := fx.New( fx.WithLogger(func() fxevent.Logger { return &myLogger{} } ), // ... ) } ``` I wrote a small demo showing a custom logger like this can be used to identify "dead functions" within Fx: https://github.com/JacobOaks/fx_dead_code_demo. This PR also adds stack trace information into the `Provided`, `Decorated`, `Supplied`, and `Decorated` fxevents to aid folks with larger codebases that consume many modules, who might otherwise have a hard time finding where exactly a "dead function" is being given to Fx with just the `name` and `ModuleName` fields of the `Run` event. Fx was already keeping track of this information, so I don't think this addition incurs too much additional overhead for Fx, but if folks disagree we can remove this addition or perhaps make it opt-in by gating it behind a new option `fx.ReportStackTraces()` or something.
alexisvisco
pushed a commit
to alexisvisco/dig
that referenced
this pull request
Aug 31, 2023
…go#377) Recently folks have been asking for more visiblity into what constructors and decorators actually get called, especially Fx users. This implementation allows users to provide callback functions for Dig to call when it invokes a constructor or decorator. Dig will pass along info such as which function was actually called, the name (package + name) of the function, and what kind it was (provided or decorated), when it calls the provided callback function. Users can provide a callback by using the new `dig.Option`, `dig.WithCallback`: ```go type MyCallback struct {} func (MyCallback) Called(ci dig.CallbackInfo) { switch ci.Kind { case dig.Provided: fmt.Printf("My provided function %q was called!\n", ci.Name) case dig.Decorated: fmt.Printf("My decorator %q was called!\n", ci.Name) } } func main() { // ... c := dig.New(WithCallback(MyCallback{})) // ... } ``` With this addition, from the Fx side, we can register a callback function that will generate new Fx events when constructors and decorators get called. This will help users identify which _do not_ get called, and thus identify dead code. Internal Ref: GO-1873
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Recently folks have been asking for more visiblity into what constructors and decorators actually get called, especially Fx users (uber-go/fx#1039).
This PR allows users to provide callback functions for Dig to call when it invokes a constructor or decorator. Dig will pass along some basic information to the callback function: the name of the function, and the error it returned if any.
Users can provide a callback by using the two new APIs,
dig.WithProviderCallbackanddig.WithDecoratorCallback, which return a type implementing bothdig.ProvideOptionanddig.DecorateOption. For example, this code prints a simple message whenmyFuncandmyDecoratorare called (presumably defined elsewhere):We can discuss Fx-side consumption of this functionality to aid observability in this way and help identify dead code, but one idea is to register callback functions that will generate new Fx events when constructors and decorators get called. I wrote a prototype implementation of this idea for Fx, and then wrote a demo showing how this can help identify dead code.
Internal Ref: GO-1873