You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
> Tip: See <doc:NetworkLogging-Article> for more information about how to configure network logging if your app does not use `URLSession` directly, how to further customize it, how to capture and display decoding errors, and more. Pulse is modular and will accommodate almost any system.
48
+
> tip: See <doc:NetworkLogging-Article> for more information about how to configure network logging if your app does not use `URLSession` directly, how to further customize it, how to capture and display decoding errors, and more. Pulse is modular and will accommodate almost any system.
Copy file name to clipboardExpand all lines: Sources/Pulse/Pulse.docc/Articles/NetworkLogging-Article.md
+34-37Lines changed: 34 additions & 37 deletions
Original file line number
Diff line number
Diff line change
@@ -13,7 +13,9 @@ Pulse works on the `URLSession` level, and it needs access to its callbacks to l
13
13
14
14
The first step is to capture network traffic.
15
15
16
-
-**Option 1 (Quickest)**. If you are evaluating the framework, the quickest way to get started is with a proxy from the **PulseProxy** module.
16
+
### Option 1 (Quickest)
17
+
18
+
If you are evaluating the framework, the quickest way to get started is with a proxy from the **PulseProxy** module.
17
19
18
20
```swift
19
21
importPulseProxy
@@ -23,9 +25,11 @@ NetworkLogger.enableProxy()
23
25
#endif
24
26
```
25
27
26
-
> Important: **PulseProxy** uses method swizzling and private APIs, and it is not recommended that you include it in the production builds of your app. It is also not guaranteed to continue working with new versions of the system SDKs.
28
+
> important: **PulseProxy** uses method swizzling and private APIs, and it is not recommended that you include it in the production builds of your app. It is also not guaranteed to continue working with new versions of the system SDKs.
29
+
30
+
### Option 2 (Recommended)
27
31
28
-
-**Option 2 (Recommended)**. Use ``NetworkLogger/URLSession``, a thin wrapper on top of `URLSession`.
32
+
Use ``NetworkLogger/URLSession``, a thin wrapper on top of `URLSession`.
``NetworkLogger/URLSession`` is the best way to integrate Pulse because it supports all `URLSession` APIs, including the new Async/Await methods. It also makes it easy to remove it conditionally.
42
46
43
-
-**Option 3.** Use ``URLSessionProxyDelegate``.
47
+
### Option 3
44
48
45
-
If you use a delegate-based `URLSession` that doesn't rely on any of its convenience APIs, such as [Alamofire](https://github.com/Alamofire/Alamofire), you can record its traffic using a proxy delegate.
49
+
If you use a delegate-based `URLSession` that doesn't rely on any of its convenience APIs, such as [Alamofire](https://github.com/Alamofire/Alamofire), you can record its traffic using ``NetworkLogger/URLSessionProxyDelegate``.
46
50
47
51
```swift
48
-
let delegate =URLSessionProxyDelegate(delegate: <#YourSessionDelegate#>)
52
+
let delegate =NetworkLogger.URLSessionProxyDelegate(delegate: <#YourSessionDelegate#>)
49
53
let session =URLSession(configuration: .default, delegate: delegate, delegateQueue: nil)
50
54
```
51
55
52
-
-**Option 4 (Manual).** Use ``NetworkLogger`` directly.
56
+
> important: This method supports a limited subset of scenarios and doesn't work with `URLSession` Async/Await APIs.
57
+
58
+
### Option 4 (Manual)
53
59
54
60
If none of the convenience APIs described earlier work for you, you can use the underlying ``NetworkLogger`` directly. For example, here is how you can use it with Alamofire's `EventMonitor`:
> tip: Make sure to capture [`URLSessionTaskMetrics`](https://developer.apple.com/documentation/foundation/urlsessiontaskmetrics) as Pulse makes a great use of them and many of the features won't work without them.
83
-
84
-
## Session Proxy (Experimental)
85
-
86
-
To capture _all_ network traffic from _all_ session, including `URLSession.shared`, you can try using ``Experimental/URLSessionProxy``.
> warning: As clearly communicate by its namespace, it's an experimental feature and it might negatively affect your networking. The way it works is by registering a custom [URLProtocol](https://developer.apple.com/documentation/foundation/urlprotocol) and using a secondary URLSession instance in it, but it can be a useful tool.
88
+
## Configure Logging
93
89
94
-
> note: Alternatively, you can give the following swizzle-based [approach](https://gist.github.com/kean/3154a5bde8e0c5e9dc3322f21ba86757) a try that is less intrusive but requires more swizzling and can't be shipped with the production code.
90
+
### Recod Decoding Errors
95
91
96
-
## Recoding Decoding Errors
97
-
98
-
The network requests usually can only be considered successful when the app was able to decode the response data. With Pulse, you can do just that and when you open the response body, it'll even highlight the part of the response that's causing the decoding error.
92
+
The network requests can only be considered successful when the app decodes the response data. With Pulse, you can do just that, and when you open the response body, it'll even highlight the part of the response causing the decoding error.
99
93
100
94
```swift
101
95
// Initial setup
102
-
let logger =NetworkLogger(configuration: .init(isWaitingForDecoding: true))
103
-
let delegate =URLSessionProxyDelegate(logger: logger, delegate: YourURLSessionDelegate()))
104
-
// ... create session
96
+
let logger =NetworkLogger {
97
+
$0.isWaitingForDecoding=true
98
+
}
99
+
let session = NetworkLogger.URLSession(configuration: .default, logger: logger)
105
100
106
-
//Somewhere else in the app where decoding is done.
101
+
//Add this to the code that performs decoding of the responses.
There is usually some sensitive information in network requests, such as passwords, access tokens, and more. It's important to keep it safe.
113
-
114
-
> tip: It's recommended to use Pulse _only_ in the debug mode.
105
+
### Exclude Information From Logs
115
106
116
-
``NetworkLogger`` captures data safely in a local database and it never leaves your device. Logs are never written to the system's logging system. But of course, logs are meant to be viewed and shared, which is why PulseUI provides sharing options. In case the logs do leave your device, it's best to redact any sensitive information.
107
+
``NetworkLogger`` captures data safely in a local database, and it never leaves your device. Logs are never written to the system's logging system. But, of course, logs are meant to be viewed and shared, which is why PulseUI provides sharing options. In case the logs do leave your device, it's best to redact any sensitive information.
117
108
118
109
``NetworkLogger/Configuration`` has a set of convenience APIs for managing what information is included or excluded from the logs.
119
110
@@ -139,15 +130,21 @@ let logger = NetworkLogger {
139
130
}
140
131
```
141
132
142
-
> tip: "Include" and "exclude" patterns support basic wildcards (`*`), but you can also turns them into full-featured regex patterns using ``NetworkLogger/Configuration/isRegexEnabled``.
133
+
You can then replace the default decoder with your custom instance:
134
+
135
+
```swift
136
+
NetworkLogger.shared= logger
137
+
```
138
+
139
+
> Tip: "Include" and "exclude" patterns support basic wildcards (`*`), but you can also turn them into full-featured regex patterns using ``NetworkLogger/Configuration/isRegexEnabled``.
143
140
144
-
If the built-in configuration options don't cover all of your use-cases, you can set``NetworkLogger/Configuration/willHandleEvent`` closure that provides you complete control for filtering out and updating the events.
141
+
If the built-in configuration options don't cover all of your usecases, you can set the``NetworkLogger/Configuration/willHandleEvent`` closure that provides you complete control for filtering out and updating the events.
145
142
146
-
> important: If you redact information manually from requests or responses, make sure to also update ``NetworkLogger/Metrics`` because individual transactions within metrics contain recorded request and response pairs.
143
+
> important: If you redact information manually from requests or responses, also update ``NetworkLogger/Metrics`` because individual transactions within metrics contain recorded request and response pairs.
147
144
148
-
## Trace in Xcode Console
145
+
###Trace in Xcode Console
149
146
150
-
While Pulse doesn't print anything in the Xcode Console by default, it's easy to enable such logging for network requests. ``LoggerStore`` re-translates all of the log events that it processes using ``LoggerStore/events`` publisher that you can leverage to log some of the recoded information in the Xcode Console.
147
+
Pulse doesn't print anything in the Xcode Console by default, but it's easy to enable logging for network requests. ``LoggerStore`` re-translates all of the log events that it processes using ``LoggerStore/events`` publisher that you can leverage.
0 commit comments