Coverage for app / backend / src / couchers / event_log.py: 100%

1from typing import Any 

2 

3from sqlalchemy.orm import Session 

4 

5from couchers.config import config 

6from couchers.context import CouchersContext 

7from couchers.models.logging import EventLog, EventSource 

8 

9 

10def log_event( 

11 context: CouchersContext, 

12 session: Session, 

13 event_type: str, 

14 /, 

15 properties: dict[str, Any], 

16 *, 

17 value: float = 1.0, 

18 _override_user_id: int | None = None, 

19) -> None: 

20 """ 

21 Record a backend analytics event. 

22 

23 Usage: 

24 log_event(context, session, "host_request.sent", {"host_id": host.id, "nights": 3}) 

25 

26 Use _override_user_id for actions where the user is known but may not be in context 

27 (e.g. signup, token-based actions): 

28 log_event(context, session, "account.signup_completed", {...}, _override_user_id=user.id) 

29 

30 If context has no user_id and no _override_user_id is given, user_id will be None (anonymous event). 

31 

32 Event type naming convention: "noun.verbed" with dot-separated hierarchy, e.g. 

33 account.login 

34 host_request.sent 

35 host_request.accepted 

36 message.sent 

37 reference.written 

38 """ 

39 user_id = _override_user_id if _override_user_id is not None else context._user_id 

40 

41 session.add( 

42 EventLog( 

43 event_type=event_type, 

44 user_id=user_id, 

45 sofa=context._sofa, 

46 version=config["VERSION"], 

47 properties=properties, 

48 value=value, 

49 source=EventSource.backend, 

50 ) 

51 )