Difference between creating and preloading the extension in a remote setup

[daamien]

Following our discussion, here's a small patch to clarify the difference between preloading and creating the powa extension inside the distant servers when deploying a remote collection setup.

[rjuju]

The remote setup documentation links to the powa-archivist documentation, which already says that:

Since PoWA 4, you need to specify powa in the shared_preload_libraries configuration ONLY if you want to store the performance data locally. For remote storage, please see the Remote setup documentation. The pg_stat_statements extension (as all other Stats Extensions) still required to be configured in the shared_preload_libraries setting.

I'm a bit worried about this wording as it's technically inaccurate. An extension cannot be "preloaded", only a module can. And not all modules come with an extension (like auto_explain). Also, "preload" isn't a wise terminology to use as there are 3 kinds of preloading possible, even if you mention which one you mean.

What if instead we change

You need to configure PoWA archivist and the Stats Extensions of your choice on each remote PostgreSQL server.

to

You need to install and configure PoWA archivist and the Stats Extensions of your choice on each remote PostgreSQL server.

and also adjust the powa-archivist documentation. Something like

As PoWA-archivist is implemented as a background worker, the library must be loaded at server start time.

to

As PoWA-archivist can provide a background worker, the library must be loaded at server start time if local metric collection is wanted.

[daamien]

Yes the remote setup documentation links to the powa-archivist... and the powa-archivist links to the Remote Setup documentation :-) Personnaly I looped multiple times between the two and that's why I though it'd be more clear to regroup the infor in the "Remote Setup" section. Even if that's a bit redundant.

Anyway I removed my changes and placed yours instead.

And Yes the vocabulary around extension management is prone to misconceptions.... My experience with PostgreSQL Anonymizer is that for most users the expression "install the extension" means "install the RPM package" or whatever OS-level installation process... So I try to stick to the following semantic rules : "install" is for the package, "load" is for the module, "create" is for the extension. But it's easy to slip and mix things up...

Basically most users don't see the difference between a module and an extension, they see powa as a whole, an agent they have to deploy on each server... Maybe we can go at the root of the problem and clarify this with a small introduction in components/powa-archivist/installation.rst

PoWA archivist is composed of 2 elements:
  * an extension named "powa" containing management functions.
  * a module name "powa"  that runs a background worker collecting the performance metadata

Creating the extension is always required but loading the module is only necessay for local metric collection.

Feel free to add or discard this.

Thanks for your time.

[rjuju]

I like your idea of clearly explaining upfront what are the 2 parts of powa-archivist and what they're for. However I think it would be better to add a new "introduction" or "what is it" paragraph before the installation part. Do you want to add that to your patch or should I take care of it?

[daamien]

I made the requested changes. I can squash the 3 commits into 1 if you prefer.

[rjuju]

Thanks! I think I can squash the commits for GH interface while still keeping the information that the PR was merged, so it should be ok. There are still some minor improvements that I'd like to make but it will be easier to add them on top of your changes, so I'll merge it now.

Thanks for the improvements!

[daamien]

Thanks for your help !