Debian Codegraph @

pkg/services/specialized/logger/doc.go

raw
1 // Package logger provides a notification service that outputs notifications to a logger.
2 //
3 // The Logger service is a specialized notification service that writes notifications
4 // to a logger instance rather than sending them to an external service. This is
5 // particularly useful for testing, debugging, or when you need to capture notification
6 // output within an application without external dependencies. The service writes
7 // messages to the standard logger configured by the consumer, making it integrate
8 // seamlessly with existing logging infrastructure.
9 //
10 // The logger service is part of the "specialized" category in Shoutrrr, which contains
11 // services that serve specific purposes beyond typical notification delivery. Unlike
12 // chat, push, or email services, the logger service doesn't communicate with external
13 // APIs but instead provides a local logging output mechanism.
14 //
15 // # URL Format
16 //
17 // The service URL follows the format:
18 //
19 // logger://
20 //
21 // The logger service does not require any host, port, or authentication parameters.
22 // The URL scheme "logger" identifies this service type. No query parameters are
23 // supported as the service has no configuration options beyond the logger instance.
24 //
25 // # Configuration Options
26 //
27 // No configuration options are available for this service. The logger service
28 // inherits from the standard service infrastructure but does not expose any
29 // additional configuration through the URL. The logger instance itself must be
30 // provided when creating the service, typically through the shoutrrr API.
31 //
32 // The Config struct is intentionally minimal and implements the EnumlessConfig
33 // interface, indicating that no enumerable configuration fields are available.
34 // This design reflects the service's purpose as a simple passthrough to the
35 // configured logger.
36 //
37 // # Templates
38 //
39 // The logger service supports message templates through the standard Shoutrrr
40 // templating system. Templates allow you to customize the output format by
41 // processing notification parameters before writing to the logger.
42 //
43 // Template variables are populated from the notification params, allowing for
44 // dynamic message formatting. For example, you can include severity levels,
45 // timestamps, or custom fields in the logged output.
46 //
47 // ## Template Example
48 //
49 // To set a template that includes a severity level:
50 //
51 // service.SetTemplateString("message", "{{.level}}: {{.message}}")
52 //
53 // Then send a notification with params:
54 //
55 // params := types.Params{"level": "warning"}
56 // service.Send("Disk space low", &params)
57 //
58 // Output: "warning: Disk space low"
59 //
60 // # Usage Examples
61 //
62 // ## Basic notification
63 //
64 // url := "logger://"
65 // err := shoutrrr.Send(url, "Hello from Shoutrrr!")
66 //
67 // ## Using with custom logger
68 //
69 // url := "logger://"
70 // logger := log.New(os.Stdout, "[shoutrrr] ", log.LstdFlags)
71 // err := shoutrrr.Send(url, "Custom logger output", &types.Params{}, logger)
72 //
73 // ## With template
74 //
75 // url := "logger://"
76 // service, err := shoutrrr.CreateService(url)
77 // if err != nil {
78 // log.Fatal(err)
79 // }
80 // err = service.SetTemplateString("message", "[{{.level}}] {{.message}}")
81 // if err != nil {
82 // log.Fatal(err)
83 // }
84 // params := types.Params{"level": "INFO"}
85 // err = service.Send("Application started", &params)
86 //
87 // # Common Use Cases
88 //
89 // ## Testing and Development
90 //
91 // The logger service is invaluable for testing notification workflows without
92 // external dependencies:
93 //
94 // url := "logger://"
95 // err := shoutrrr.Send(url, "Test notification")
96 //
97 // ## Debugging Notification Flows
98 //
99 // Capture and inspect notification messages during development:
100 //
101 // url := "logger://"
102 // err := shoutrrr.Send(url, "Debug: "+jsonString)
103 //
104 // ## Centralized Logging Integration
105 //
106 // Route notifications through your application's existing logging infrastructure:
107 //
108 // url := "logger://"
109 // customLogger := log.New(logFile, "[notifications] ", log.LstdFlags)
110 // err := shoutrrr.Send(url, message, params, customLogger)
111 //
112 // ## Piping Notifications
113 //
114 // Combine with other services for complex notification routing:
115 //
116 // // Log all outgoing notifications
117 // loggerService, _ := shoutrrr.CreateService("logger://")
118 // // Process and forward to other services...
119 //
120 // # Error Handling
121 //
122 // The logger service has minimal error conditions since it doesn't communicate
123 // with external services. However, errors can occur in the following scenarios:
124 //
125 // err := shoutrrr.Send(url, message)
126 // if err != nil {
127 // log.Printf("Failed to log notification: %v", err)
128 // }
129 //
130 // Error scenarios:
131 // - Template execution failure (invalid template syntax or missing fields)
132 // - Logger write failures (if the underlying logger encounters an error)
133 // - Nil logger (if no logger was provided during initialization)
134 //
135 // # Security Considerations
136 //
137 // The logger service has minimal security implications since it doesn't transmit
138 // data externally. However, consider the following:
139 //
140 // - Message content written to logs may contain sensitive information
141 // - Ensure your logging backend is properly secured
142 // - Be aware of log rotation policies to prevent disk space issues
143 // - Consider log levels - verbose notification logging may increase log volume
144 // - Template variables could potentially expose internal data if logged improperly
145 //
146 // # Limitations and Behaviors
147 //
148 // - No network communication is performed; all output goes to the configured logger
149 // - No authentication or authorization is required
150 // - No configuration parameters are available through the URL
151 // - The logger must be provided during service initialization
152 // - Template support is limited to the message field
153 // - The service always returns successfully unless template execution fails
154 // - Message content is written as-is without any transformation (except templates)
155 // - The service ID is "logger" for programmatic identification
156 package logger