Pass debug flag into template (Nunjuck and filters)

[Tenischev]

Reason/Context

In the #363 debug flag was extended to provide more information, this is nice feature which could be pleasant in templates.
Pass debug flag in the way that it will be available in Nunjuck and so in filters.

Description

Maybe it's make sense to reserve parameter like generator-debug which will be true if you run generator with --debug. Not just debug because parameter with such name could be useful for template itself.

[derberg]

I'm not sure we have to overcomplicate with some additional params, especially reserved ones. Here we should look at the UX more, and the user that will trigger generation. Users will not have a strong knowledge of tooling and should not be forced to think about debugging generator or debugging template, but debugging generation process, which involves both, generator and template. We should think about the generator as a helper/framework in my opinion, and templates as specific generators, that just use the framework. So you debug generation process, and not one or another project.

Anyway, it would be awesome to see it implemented. I saw that some filters in some templates have console.log commented out and used only for development. Debug would enable you to finally introduce those logs the good way, so they are not comments that you have to uncomment, and then comment again. Such DX sucks and this issue will improve it.

[fmvilas]

I'd instead use something like https://www.npmjs.com/package/debug.

This way we could do:

DEBUG=template:filters:* DEBUG=generator:* ag asyncapi.yaml...

It's pretty much the standard way of debugging apps these days.

[derberg]

debug examples about using env variables are ok but for microservices world. CLI is different though, debug should be super simple to turn on and off. It should be part of the CLI options and not overcomplicated. Nevertheless, I agree that outcome should be that in the logs, once you turn on debug you see clearly what errors come from templates and what from generator

[fmvilas]

Why choosing? Just make --debug to set the DEBUG env to something like generator:*. In my opinion, this is not just for microservices, CLIs also benefit when they run on CIs and deployments. Depending on the environment, you may want to see more or less logs (not levels but scopes) and you may also want to see the logs of the tools we use internally for a better debugging experience. And all of them use the debug package.

Try using the DEBUG env with any CLI tool, you would be surprised 😄

[derberg]

Nothing against debug but as mentioned, setting debug with env flags and not CLI options.
I just do not like experience like DEBUG=generator:* ag asyncapi.yaml

And I checked DEBUG with GitHub CLI and npm and got only disappointed 😛 it can't be better than doing mycli --help and getting hints with all options, including debug

My past experience is, control server with environment variables, but with CLI stick to CLI options.

[fmvilas]

We're talking 2 different things here. With a debug param like --debug you get all the messages from Generator while with the env var you control what to see exactly. For instance, if I'm debugging the hooks registration process I could do DEBUG=generator:hooks:register ag ... and remove all the noise of the other parts. Or I may just want to see my template messages and not the Generator ones and so I do DEBUG=html-template:* ag .... That's why I was suggesting that we could have a debug param like --debug html-template:* which will internally set the env var.

I just do not like experience like DEBUG=generator:* ag asyncapi.yaml

I love it. It gives me control :) Although, using the syntax described above would be better maybe. Also, don't forget that some people will use the Generator in CI systems and you might want to have certain logs depending on your environment. Same command, different logs options depending on the env var. For instance, I may want to see some logs on staging but not on production. Or I'm having trouble and want to see what's happening. Changing an environment variable is usually handier than re-deploying to see logs.

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity 😴
It will be closed in 30 days if no further activity occurs. To unstale this issue, add a comment with detailed explanation.
Thank you for your contributions ❤️

[derberg]

update

Generator CLI will be removed, as AsyncAPI CLI supports generator now. So there is no need to discuss if debug should be used here or not, as there are no flags as --debug here.

so scope is:

• introduce https://www.npmjs.com/package/debug
• best to start simple and have 3 debug levels: all, from generator only, from template only
• make sure debug is passed to templates and it is document how to use it

breaking change?

if we go with debug package and environment variables approach, do we just remove debug option from the library or just leave it and make it work the way that if it is used, then DEBUG=* is used?

[Gmin2]

is this still valid? (After nunjucks depreciation)

cc @derberg

[derberg]

yes, we still need it in templates, no matter what rendering engine is used, we still need unified logging

[ItshMoh]

Is it still valid? If so I would like to work on it @derberg

[derberg]

we need to first decide if we stay with current logger solution or not