Skip to content

Commit a6dc00e

Browse files
selectiveduplicateselectiveduplicate
authored
Update README (#23)
1 parent d6d54a0 commit a6dc00e

File tree

2 files changed

+295
-51
lines changed

2 files changed

+295
-51
lines changed

‎README.md

+295-51
Original file line numberDiff line numberDiff line change
@@ -1,30 +1,53 @@
1-
# Moesif Python Requests
1+
# Moesif for Python Requests
2+
by [Moesif](https://moesif.com), the [API analytics](https://www.moesif.com/features/api-analytics) and [API monetization](https://www.moesif.com/solutions/metered-api-billing) platform.
23

34
[![Built For][ico-built-for]][link-built-for]
45
[![Latest Version][ico-version]][link-package]
56
[![Language Versions][ico-language]][link-language]
67
[![Software License][ico-license]][link-license]
78
[![Source Code][ico-source]][link-source]
89

9-
Interceptor for Python Requests lib to capture _outgoing_ API calls and sends to [Moesif](https://www.moesif.com) for API analytics and monitoring.
10+
It's an interceptor for Python Requests library that captures outgoing API calls and sends to [Moesif](https://www.moesif.com) for API analytics and monitoring.
1011

11-
_If you are using Moesif's API monitoring SDKs like [Moesif Django](https://github.com/Moesif/moesifdjango) or [Moesif WSGI](https://github.com/moesif/moesifwsgi) to log incoming API calls, this library is already included._
12+
> If you're new to Moesif, see [our Getting Started](https://www.moesif.com/docs/) resources to quickly get up and running.
1213
13-
## How to install
14+
> If you are using Moesif's API monitoring SDKs like [Moesif Django](https://github.com/Moesif/moesifdjango) or [Moesif WSGI](https://github.com/moesif/moesifwsgi) to log incoming API calls, this library is already included.
15+
16+
## Prerequisites
17+
Before using this middleware, make sure you have the following:
18+
19+
- [An active Moesif account](https://moesif.com/wrap)
20+
- [A Moesif Application ID](#get-your-moesif-application-id)
21+
22+
### Get Your Moesif Application ID
23+
After you log into [Moesif Portal](https://www.moesif.com/wrap), you can get your Moesif Application ID during the onboarding steps. You can always access the Application ID any time by following these steps from Moesif Portal after logging in:
24+
25+
1. Select the account icon to bring up the settings menu.
26+
2. Select **Installation** or **API Keys**.
27+
3. Copy your Moesif Application ID from the **Collector Application ID** field.
28+
<img class="lazyload blur-up" src="images/app_id.png" width="700" alt="Accessing the settings menu in Moesif Portal">
29+
30+
## Install
31+
Install with pip:
1432

1533
```shell
1634
pip install moesifpythonrequest
1735
```
1836

19-
Import the Moesif lib and call start_capture_outgoing.
20-
Moesif will start logging all API calls made from the requests lib.
37+
## Configure
38+
See the available [configuration options](#configuration-options) to learn how to configure the middleware for your use case.
39+
40+
## How to Use
41+
42+
Import the Moesif library and call the `start_capture_outgoing` method.
43+
Moesif will start logging all API calls made from the Requests library.
2144

2245
```python
2346
from moesifpythonrequest.start_capture.start_capture import StartCapture
2447
import requests
2548

2649
moesif_settings = {
27-
'APPLICATION_ID': 'Your Moesif Application Id'
50+
'APPLICATION_ID': 'YOUR_MOESIF_APPLICATION_ID'
2851
}
2952

3053
def main():
@@ -36,56 +59,277 @@ StartCapture().start_capture_outgoing(moesif_settings)
3659
main()
3760
```
3861

39-
Your Moesif Application Id can be found in the [_Moesif Portal_](https://www.moesif.com/).
40-
After signing up for a Moesif account, your Moesif Application Id will be displayed during the onboarding steps.
41-
42-
## Configuration options
43-
44-
### __`APPLICATION_ID`__
45-
46-
(required) _string_, Your Moesif Application Id which can be found by logging
47-
into the [_Moesif Portal_](https://www.moesif.com/), click on the top right menu,
48-
and then clicking _Installation_.
49-
50-
### __`GET_METADATA_OUTGOING`__
51-
52-
(optional) _(req, res) => dictionary_, a function that enables you to return custom metadata associated with the logged API calls.
53-
Takes in the [Requests](http://docs.python-requests.org/en/master/api/) request and response object as arguments. You should implement a function that
54-
returns a dictionary containing your custom metadata. (must be able to be encoded into JSON). For example, you may want to save a VM instance_id, a trace_id, or a resource_id with the request.
62+
Replace *`YOUR_MOESIF_APPLICATION_ID`* with [your Moesif Application ID](#get-your-moesif-application-id).
5563

56-
### __`IDENTIFY_USER_OUTGOING`__
64+
For a general troubleshooting guide that can help you solve common problems, see [Server Troubleshooting Guide](https://www.moesif.com/docs/troubleshooting/server-troubleshooting-guide/).
5765

58-
(optional, but highly recommended) _(req, res) => string_, a function that takes [Requests](http://docs.python-requests.org/en/master/api/) request and response, and returns a string that is the user id used by your system. While Moesif tries to identify users automatically,
59-
but different frameworks and your implementation might be very different, it would be helpful and much more accurate to provide this function.
66+
Other troubleshooting supports:
6067

61-
### __`IDENTIFY_COMPANY_OUTGOING`__
68+
- [FAQ](https://www.moesif.com/docs/faq/)
69+
- [Moesif support email](mailto:[email protected])
6270

63-
(optional) _(req, res) => string_, a function that takes [Requests](http://docs.python-requests.org/en/master/api/) request and response, and returns a string that is the company id for this event.
71+
## Repository Structure
6472

65-
### __`GET_SESSION_TOKEN_OUTGOING`__
66-
67-
(optional) _(req, res) => string_, a function that takes [Requests](http://docs.python-requests.org/en/master/api/) request and response, and returns a string that is the session token for this event. Again, Moesif tries to get the session token automatically, but if you setup is very different from standard, this function will be very help for tying events together, and help you replay the events.
68-
69-
### __`LOG_BODY_OUTGOING`__
70-
71-
(optional) _boolean_, default True, Set to False to remove logging request and response body.
72-
73-
### __`SKIP_OUTGOING`__
74-
75-
(optional) _(req, res) => boolean_, a function that takes a [Requests](http://docs.python-requests.org/en/master/api/) request and response,
76-
and returns true if you want to skip this particular event.
77-
78-
### __`MASK_EVENT_MODEL`__
79-
80-
(optional) _(EventModel) => EventModel_, a function that takes a [Moesif EventModel](https://github.com/Moesif/moesifapi-python/blob/master/moesifapi/models/event_model.py) and returns an EventModel with desired data removed. For details regarding EventModel please see the [Moesif Python API Documentation](https://www.moesif.com/docs/api?python).
81-
82-
## Example
83-
84-
An example Moesif integration is [available on GitHub](https://github.com/Moesif/moesif-python-outgoing-example)
85-
86-
## Other integrations
73+
```
74+
.
75+
├── images/
76+
├── LICENSE
77+
├── MANIFEST.in
78+
├── moesifpythonrequest/
79+
├── README.md
80+
├── register.py
81+
├── requirements.txt
82+
├── setup.cfg
83+
└── setup.py
84+
```
8785

88-
To view more documentation on integration options, please visit __[the Integration Options Documentation](https://www.moesif.com/docs/getting-started/integration-options/).__
86+
## Configuration options
87+
The following sections describe the available configuration options. You have to set these options in a Python dictionary and pass that as an argument as you call the `start_capture_outgoing` method. See the [example]([#examples](https://github.com/Moesif/moesif-python-outgoing-example/blob/836b1f38be6e3ccc08c840ab328af501375fa849/main.py#L31)) for better understanding.
88+
89+
### `APPLICATION_ID` (Required)
90+
<table>
91+
<tr>
92+
<th scope="col">
93+
Data type
94+
</th>
95+
</tr>
96+
<tr>
97+
<td>
98+
String
99+
</td>
100+
</tr>
101+
</table>
102+
103+
A string that [identifies your application in Moesif](#get-your-moesif-application-id).
104+
105+
### `GET_METADATA_OUTGOING`
106+
table>
107+
<tr>
108+
<th scope="col">
109+
Data type
110+
</th>
111+
<th scope="col">
112+
Parameters
113+
</th>
114+
<th scope="col">
115+
Return type
116+
</th>
117+
</tr>
118+
<tr>
119+
<td>
120+
Function
121+
</td>
122+
<td>
123+
<code>(req, res)</code>
124+
</td>
125+
<td>
126+
Dictionary
127+
</td>
128+
</tr>
129+
</table>
130+
131+
Optional.
132+
133+
A function that enables you to return custom metadata associated with the logged API calls.
134+
135+
Takes in the [Requests](http://docs.python-requests.org/en/master/api/) request and response objects as arguments.
136+
137+
We recommend that you implement a function that
138+
returns a dictionary containing your custom metadata. The dictionary must be a valid one that can be encoded into JSON. For example, you may want to save a virtual machine instance ID, a trace ID, or a resource ID with the request.
139+
140+
### `IDENTIFY_USER_OUTGOING`
141+
<table>
142+
<tr>
143+
<th scope="col">
144+
Data type
145+
</th>
146+
<th scope="col">
147+
Parameters
148+
</th>
149+
<th scope="col">
150+
Return type
151+
</th>
152+
</tr>
153+
<tr>
154+
<td>
155+
Function
156+
</td>
157+
<td>
158+
<code>(req, res)</code>
159+
</td>
160+
<td>
161+
String
162+
</td>
163+
</tr>
164+
</table>
165+
166+
Optional, but highly recommended.
167+
168+
A function that takes [Requests](http://docs.python-requests.org/en/master/api/) request and response objects, and returns a string that represents the user ID used by your system.
169+
170+
While Moesif tries to identify users automatically, different frameworks and your implementation might vary. So we highly recommend that you accurately provide a
171+
user ID using this function.
172+
173+
### `IDENTIFY_COMPANY_OUTGOING`
174+
<table>
175+
<tr>
176+
<th scope="col">
177+
Data type
178+
</th>
179+
<th scope="col">
180+
Parameters
181+
</th>
182+
<th scope="col">
183+
Return type
184+
</th>
185+
</tr>
186+
<tr>
187+
<td>
188+
Function
189+
</td>
190+
<td>
191+
<code>(req, res)</code>
192+
</td>
193+
<td>
194+
String
195+
</td>
196+
</tr>
197+
</table>
198+
199+
Optional.
200+
201+
A function that takes [Requests](http://docs.python-requests.org/en/master/api/) request and response objects and returns a string that represents the company ID for this event.
202+
203+
204+
### `GET_SESSION_TOKEN_OUTGOING`
205+
<table>
206+
<tr>
207+
<th scope="col">
208+
Data type
209+
</th>
210+
<th scope="col">
211+
Parameters
212+
</th>
213+
<th scope="col">
214+
Return type
215+
</th>
216+
</tr>
217+
<tr>
218+
<td>
219+
Function
220+
</td>
221+
<td>
222+
<code>(req, res)</code>
223+
</td>
224+
<td>
225+
String
226+
</td>
227+
</tr>
228+
</table>
229+
230+
Optional.
231+
232+
A function that takes [Requests](http://docs.python-requests.org/en/master/api/) request and response objects, and returns a string that corresponds to the session token for this event.
233+
234+
Similar to [user IDs](#identify_user_outgoing), Moesif tries to get the session token automatically. However, if you setup differs from the standard, this function can help tying up events together and help you replay the events.
235+
236+
### `LOG_BODY_OUTGOING`
237+
<table>
238+
<tr>
239+
<th scope="col">
240+
Data type
241+
</th>
242+
<th scope="col">
243+
Default
244+
</th>
245+
</tr>
246+
<tr>
247+
<td>
248+
Boolean
249+
</td>
250+
<td>
251+
<code>True</code>
252+
</td>
253+
</tr>
254+
</table>
255+
256+
Optional.
257+
258+
Set to `False` to remove logging request and response body.
259+
260+
### `SKIP_OUTGOING`
261+
<table>
262+
<tr>
263+
<th scope="col">
264+
Data type
265+
</th>
266+
<th scope="col">
267+
Parameters
268+
</th>
269+
<th scope="col">
270+
Return type
271+
</th>
272+
</tr>
273+
<tr>
274+
<td>
275+
Function
276+
</td>
277+
<td>
278+
<code>(req, res)</code>
279+
</td>
280+
<td>
281+
Boolean
282+
</td>
283+
</tr>
284+
</table>
285+
286+
Optional.
287+
288+
A function that takes a [Requests](http://docs.python-requests.org/en/master/api/) request and response objects,
289+
and returns `True` if you want to skip this particular event.
290+
291+
### `MASK_EVENT_MODEL`
292+
<table>
293+
<tr>
294+
<th scope="col">
295+
Data type
296+
</th>
297+
<th scope="col">
298+
Parameters
299+
</th>
300+
<th scope="col">
301+
Return type
302+
</th>
303+
</tr>
304+
<tr>
305+
<td>
306+
Function
307+
</td>
308+
<td>
309+
<code>(EventModel)</code>
310+
</td>
311+
<td>
312+
<code>EventModel</code>
313+
</td>
314+
</tr>
315+
</table>
316+
317+
Optional.
318+
319+
A function that takes the final Moesif event model and returns an `EventModel` object with desired data removed.
320+
321+
For more information about Moesif event model, see [Moesif Python API documentation](https://www.moesif.com/docs/api?python).
322+
323+
## Examples
324+
325+
An example Moesif integration is [available on GitHub](https://github.com/Moesif/moesif-python-outgoing-example).
326+
327+
## Explore Other Integrations
328+
329+
Explore other integration options from Moesif:
330+
331+
- [Server integration options documentation](https://www.moesif.com/docs/server-integration//)
332+
- [Client integration options documentation](https://www.moesif.com/docs/client-integration/)
89333

90334
[ico-built-for]: https://img.shields.io/badge/built%20for-python%20requests-blue.svg
91335
[ico-version]: https://img.shields.io/pypi/v/moesifpythonrequest.svg

‎images/app_id.png

68 KB
Loading

0 commit comments

Comments
 (0)