Share some metrics between the Prometheus exporter and the phone home stats

[babolivier]

This PR adds a way to share some data between the prometheus exporter and the phone home stats (and wherever else we might want to share these stats with in the future, eg with modules). For now this is only used to expose the daily active users count, but can be expanded to cover other metrics.

The new test doesn't pass yet so I need to figure that out, but I've verified that the change works manually so I don't think it should block review. edit: fixed now

[babolivier]

This feels very boilerplatey currently but the idea is that we can add to this method if we add new metrics to this class.

[reivilibre]

I would be tempted to separate the stages of:

• collecting the metrics (c.f. other comment; return a SharedUsageMetrics dataclass)
• updating the gauges, given a SharedUsageMetrics object

One function per metric does feel a bit too boilerplatey to me.

as an idea

async def _collect(self) -> SharedUsageMetrics:
    return SharedUsageMetrics(
		daily_active_users=await self._store.count_daily_users()
    )

async def _update_gauges(self, metrics: SharedUsageMetrics) -> None:
    current_dau_gauge.set(metrics.daily_active_users)

Just my opinion, but I like that a bit better

[babolivier]

So we would generate a new object each time we collect metrics? That sounds fairly inefficient to me.

[babolivier]

I've implemented this idea in a slightly different way from your proposal, lmk what you think.

[reivilibre]

So we would generate a new object each time we collect metrics? That sounds fairly inefficient to me.

I think it's not a big cost for the clarity it gives. Remember this is Python where basically everything, even integers, are objects, so one more object isn't going to be much harm (especially if it uses slots).
The object is being removed in such a way that should be friendly with Python's refcounting so I don't think there's much of a garbage collection cost here either.

I would prefer the way I proposed as each metric is more self-contained in the code; the current proposal has the metric being updated differently in two branches and stored in an intermediate variable; it feels clunkier.

Even supposing objects were more inefficient, this is infrequently run that I don't think it's worth premature optimisation, better to simplify the code to reduce footgun potential I think

[babolivier]

I disagree. Even though, as you mention, the gain in optimising this is pretty negligible (for now at least, there's always the possibility that something else starts using it, such as modules), to me creating a new object everytime something requests it is a bad code smell. Plus I think the code would be more confusing that way, because then we'd be updating the prometheus gauge every 5 minutes by reading the count from the database and then when the phone home stats ask for them we'd do the whole dance again. It feels both more logical and more efficient to me to have the CommonUsageMetricsManager keep a copy of the metrics in memory, keep that updated, and serve it whenever necessary.

[reivilibre]

Can you substantiate why you think it's a code smell? Creating an object or struct to hold associated values is such an accepted pattern elsewhere that I'm surprised it's objectionable. (In fact, mutating the existing objects that you've already handed out is usually considered an awful crime, to the point that some disciplines insist on immutability in many places.)

I think the worse code smell here is not keeping the logic for one metric in one place, e.g. if you have metrics A B and C then the code locality looks like:

1st proposal:

self.stats = Stats(
    a=count_a(),
    b=count_b(),
    c=count_c(),
)

2nd proposal:

a = count_a()
b = count_b()
c = count_c()
if ..:
    self.stats = Stats(a=a, b=b, c=c)
else:
    self.stats.a = a
    self.stats.b = b
    self.stats.c = c

If we annotate the two proposals' lines with which metric they concern, you can see my point here that the locality of behaviour is improved in the first suggestion (which I believe is better for its readability):

1st proposal:

self.stats = Stats(
    a=count_a(), # A
    b=count_b(), # B
    c=count_c(), # C
)

2nd proposal:

a = count_a() # A
b = count_b() # B
c = count_c() # C
if ..:
    self.stats = Stats(a=a, b=b, c=c) # A, B, C
else:
    self.stats.a = a # A
    self.stats.b = b # B
    self.stats.c = c # C

I also think the branch here is just more clutter than it's worth. Pessimistically, this is now twice as much to go wrong and twice as much to test.

the gain in optimising this is pretty negligible (for now at least, there's always the possibility that something else starts using it, such as modules)

I will note that I don't think the gain is pretty negligible — I think it's highly dubious; we create objects all the time in Synapse and in Python generally, whether they're integers, tuples, or instances of classes.

Of course, if we really want to talk about such tiny optimisations, then we might instead consider whether introducing an if here is bad because branching is inefficient, or we might consider that increasing the size of the code in the function is bad because you're going to increase the size of this function's code, therefore making caches ineffective.
I don't think any of these are seriously relevant here, but I do think that code clarity and keeping it easier to maintain is a big bonus generally.

Plus I think the code would be more confusing that way, because then we'd be updating the prometheus gauge every 5 minutes by reading the count from the database and then when the phone home stats ask for them we'd do the whole dance again.

I think you misunderstand my statement here (hopefully having spelled out the proposals above clarifies it?). You don't have to recalculate each and every time we request it, just the style of handing back the record can be different; just always create a new record when updating the metrics rather than mutating the previous one.

[babolivier]

I think you misunderstand my statement here (hopefully having spelled out the proposals above clarifies it?). You don't have to recalculate each and every time we request it, just the style of handing back the record can be different; just always create a new record when updating the metrics rather than mutating the previous one.

Ah, I was misunderstanding it indeed. You initial proposal of _update_gauges taking metrics as an argument somehow made me assume something else than the CommonUsageMetricsManager would be handing over a metrics object to use to update the gauges, which made me super confused as to where it's supposed to be coming from. I think I see what you have in mind now, and it does make sense.

[reivilibre]

overall idea seems good, just minor thoughts

[reivilibre]

I'm not a fan of having each field have a sentinel value; it gives the impression that we may end up reporting -1 (although I see that you update upon initialisation). IMO we shouldn't report anything rather than report negative values. I can see this being potentially troublesome for the phone-home stats when we sum DAUs.

I think I would be tempted to restructure this a bit:

• rename to SharedUsageMetricsManager or equivalent (not sure what the conventional term is in Synapse ... is it Controller?)
• make SharedUsageMetrics a plain dataclass/attrs object, with daily_active_users as an int field
• put a latest(): Optional[SharedUsageMetrics] method (or field maybe?) on SharedUsageMetricsManager

(N.B. I was going to suggest that the metrics be lazily computed, either on-phone-home or on-prometheus-scrape, but I realise we don't want to block the prometheus scrape endpoint on Twisted's reactor in case everything is going awry)

This sort of design prevents having individual metrics having sentinel values like -1, which may escape.

[reivilibre]

I would be tempted to separate the stages of:

• collecting the metrics (c.f. other comment; return a SharedUsageMetrics dataclass)
• updating the gauges, given a SharedUsageMetrics object

One function per metric does feel a bit too boilerplatey to me.

as an idea

async def _collect(self) -> SharedUsageMetrics:
    return SharedUsageMetrics(
		daily_active_users=await self._store.count_daily_users()
    )

async def _update_gauges(self, metrics: SharedUsageMetrics) -> None:
    current_dau_gauge.set(metrics.daily_active_users)

Just my opinion, but I like that a bit better