Telemetría :: :telemetry convenient wrapper

I am glad to announce the first Telemetria release. https://hexdocs.pm/telemetria

It takes care of event registration (through compilation manifest), runtime and release configs (through config provider), and basically allows to wrap any expressions and/or functions to “telemetryized” calls.

If you hesitated to add telemetry to your project, it’s a great time. Example from docs:

defmodule MyMod do
  import Telemetria

  defpt pi, do: 3.14
  deft answer, do: 42 - pi()

  def inner do
    short_result = t(42 * 42)
    result =
      t do
        # long calculations
        :ok
      end
  end
end

Enjoy. Mode details are in the linked above docs. Feedback is very welcome, as always.

1 Like

I can’t tell anything about how it’s working. But one thing keeps me away from using it: the cryptic names.
Reading deft, defpt, t in some code doesn’t tell me anything about what is it then it makes the understanding harder imo.

1 Like

Well, either one uses telemetry or not.

If one uses it, each keystroke matters. And since deft stands for def+t and t for telemetry, I am positive it’s not as hard to memorize.

Imagine if Kernel.defp/2 macro was called Kernel.define_private_function/2.

Could you expand a bit on what this does? I don’t understand the code snippet.

The link in the very first line leads to the more-or-less detailed documentation.

After reading the example and the documentation it’s still not clear to me what this library does, some more detail and examples would be useful! Thanks

1 Like

Random notes:

  • English nitpick: “macroses” => “macros”
  • English nitpick: “sware about” => “aware about”
  • I’d like the option to not have t be the default wrapping block. Could be something like report_duration (not sure I am getting this right so the name could be very off) and then you could also have a module we could use like this: use Telemetria.Shortcuts which aliases the longer name to t?
  • I am not versed in :telemetry at all so to me the statement about telemetry: false is confusing. Not saying programmers shouldn’t do our homework but in my eyes, if you went through the trouble to make an easier-to-use wrapper, you might as well also add some hand-holding quick explanations about :telemetry itself.
  • Similar to above and due to me not being caught up with the :telemetry module, I have zero clue what deft and defpt wrap in terms of def or defp exactly? Are deft and defpt functions that always yield telemetry events?

I am grateful for your efforts. But to me an even better onboarding would be to include things that you seem to find superfluous and/or easy to locate in other sources. It’d save time for interested users like myself if all needed info to start with :telemetry was in your docs as well.

OK, I will try.

deft/2 and defpt/2 are simply wrappers for Kernel.def/2 and Kernel.defp/2 respectively. They are somewhat similar to AOP around aspect, mesauring the time spent in the function itself and sending the telemetry event.

t/2 does the same for anonymous functions and expressions. The latter also allows to pass context as the second parameter to be attached to the event.

Events automatically get the names based on modules / functions (configurable) and the events are registered within :telemetry automagically by a compiler.

In general, it allows to have zero boilerplate when working with complicated/huge set of :telemetry events.

I hope it became a bit clearer.

1 Like

Thanks, fixed!

Sounds reasonable. I’d love to collect more opinions, but atm I think that’s the way to go.

Basically one might configure functions that would be excluded from wrapping into :telemetry despite they are still declared with deft/defpt with zero overhead (compile-time purge.)

I honestly thought :telemetry is something like Jason nowadays, everyone should have at least read about; Phoenix docs mention it, Ecto docs do, etc.

I will try to add a couple of sentences, but I definitely want to avoid being DHH here. If one have never heard about :telemetry, they probably should have started with :telemetry itself to understand how it works in a nutshell, and only then come for libraries hiding the boilerplate.

:telemetry is a side effect. Both would behave exactly as def/2 and defp/2 from the consumer point of view. Only side effect of sending :telemetry events would happen under the hood.

1 Like

BTW, you always might do

  import Telemetria, except: [t: 2]
  ...

    Telemetria.t do
      ...
    end
1 Like

Sure, that’s your choice to make and I am not trying to change your mind. It’s simply my observation that very fast onboarding makes people much more likely to use a library. When all the info is at the same page, people are more willing to try.

I know what :telemetry is, it’s just that I never used it so far (and I want to). What I was saying was that your library could have finally made me try it but not if I have to dig separately. :slight_smile: I openly used the term “hand-holding” and I meant it. :003:

But again, it’s your choice. Thanks for sharing your thought process. :023:

Oh, that’s much better, thank you.

Do it :slight_smile:

Just add the package, update a compiler list, declare any function with deft/2 instead of def/2 and see what happens :slight_smile:

There is a typo there, should be Telemetria.

Looks neat! Just submitted a PR to fix a couple typos, look forward to trying out!

1 Like

This is pretty cool, @mudasobwa! Thanks for sharing.

Thoughts on the decorator pattern for something like this?

@decorator telemetria # the decorator could be anything. t, track, emit, report, etc.
def my_function() do
  my code |> my other code
end

It’s a pattern I use regularly and makes code pretty easy-to-read. Spandex uses it too.

Code & docs.

2 Likes

Thank you, merged. Appreciate it.

Please feel free to open issues as they arise.

Thanks!

I thought about allowing to declare telemetry aspects through module attributes, but I frankly don’t see any reason to include decorators in the library itself. Whether one wants to use a decorator, or any other implementation of AOP, t/2 is already there, exported, and nothing can prevent from doing somewhat like

@decorator telemetria()
def my_fun, do: my_code

with a decorator delegating to t/2. SRP :slight_smile:

OTOH, maybe you are right and I should think about optional support when decorators are already used in the target application.

UPD

  • 0.5.0
    • [ENH] annotation @telemetria true as a synonym to deft/2
    • [FIX] polling is off by default
  • 0.4.0
    • [ENH] default polling of system / vm states for free
    • [ENH] starting in phases ensuring proper instrumenter setup
  • 0.3.0
    • [ENH] no need for any config in any environment
    • [BUG] proper handling of guards in compiler, correct event names

The module attribute @telemetria accepts true only ATM, but it will be extended to accept additional context, levels and specific handler.

Just blogged on why Telemetría, what is it, what is it not, how to use etc.

3 Likes