|
8 | 8 |
|
9 | 9 | [](https://travis-ci.com/getsentry/sentry-python) |
10 | 10 |
|
11 | | -***Sentry-Python is still under development and not yet documented*** For a |
12 | | -stable SDK, use [raven](https://github.com/getsentry/raven-python). |
| 11 | +- [Documentation](https://docs.sentry.io/quickstart/?platform=python) |
13 | 12 |
|
14 | | -## Getting started with the new Sentry SDK for Python |
| 13 | +# License |
15 | 14 |
|
16 | | -Install this package with ``pip install sentry-sdk``. Then, in your code: |
17 | | - |
18 | | -```python |
19 | | -import sentry_sdk |
20 | | -sentry_sdk.init(dsn="https://foo@sentry.io/123") |
21 | | -``` |
22 | | - |
23 | | -After initialization, you can capture exceptions like this: |
24 | | - |
25 | | -```python |
26 | | -sentry_sdk.capture_exception(ValueError()) |
27 | | - |
28 | | -try: |
29 | | - raise ValueError() |
30 | | -except Exception: |
31 | | - sentry_sdk.capture_exception() |
32 | | -``` |
33 | | - |
34 | | -...or send messages: |
35 | | - |
36 | | -```python |
37 | | -sentry_sdk.capture_message("Hi Sentry!") |
38 | | -``` |
39 | | - |
40 | | -## Scopes (contexts, tags) |
41 | | - |
42 | | -You can create a scope to attach data to all events happening inside of it: |
43 | | - |
44 | | -```python |
45 | | -with sentry_sdk.Hub.current.push_scope(): |
46 | | - with sentry_sdk.configure_scope() as scope: |
47 | | - scope.transaction = "my_view_name" |
48 | | - scope.set_tag("key", "value") |
49 | | - scope.user = {"id": 123} |
50 | | - |
51 | | - # ValueError event will have all that data attached |
52 | | - capture_exception(ValueError()) |
53 | | - |
54 | | -# This one not since it is outside of the context manager |
55 | | -capture_exception(ValueError()) |
56 | | -``` |
57 | | - |
58 | | -Scopes can be nested. If you call ``push_scope`` inside of the |
59 | | -``with``-statement again, that scope will be pushed onto a stack. It will also |
60 | | -inherit all data from the outer scope. |
61 | | - |
62 | | -### Scopes in unconfigured environments |
63 | | - |
64 | | -If you never call ``init``, no data will ever get sent to any server. In such |
65 | | -situations, code like this is essentially deadweight: |
66 | | - |
67 | | -```python |
68 | | -with sentry_sdk.configure_scope() as scope: |
69 | | - scope.user = _get_user_data() |
70 | | -``` |
71 | | - |
72 | | -Sentry-Python supports an alternative syntax for configuring a scope that |
73 | | -solves this problem: |
74 | | - |
75 | | -```python |
76 | | -@sentry_sdk.configure_scope |
77 | | -def _(scope): |
78 | | - scope.user = _get_user_data() |
79 | | -``` |
80 | | - |
81 | | -Your function will just not be executed if there is no client configured. |
82 | | - |
83 | | -In your testing and development environment you still might want to run that |
84 | | -code without sending any events. In that case, simply call ``init`` without a |
85 | | -DSN: |
86 | | - |
87 | | -```python |
88 | | -sentry_sdk.init() |
89 | | -``` |
90 | | - |
91 | | -### Breadcrumbs |
92 | | - |
93 | | -Breadcrumbs also live on the stack. By default any (non-debug) log message |
94 | | -anywhere in your system ends up as a breadcrumb, see [the logging |
95 | | -docs](./docs/logging.md) for more information. You can, however, also create |
96 | | -breadcrumbs manually: |
97 | | - |
98 | | -```python |
99 | | -sentry_sdk.add_breadcrumb( |
100 | | - timestamp=datetime.datetime.now(), |
101 | | - type="log", |
102 | | - level="debug", |
103 | | - # message="hi", |
104 | | - # category="myapp.models", |
105 | | -}) |
106 | | -``` |
107 | | - |
108 | | -You can also pass a callback to `add_breadcrumb` like so: |
109 | | - |
110 | | -```python |
111 | | -sentry_sdk.add_breadcrumb(lambda: { |
112 | | - "timestamp": datetime.datetime.now(), |
113 | | - "type": "log", |
114 | | - "level": "debug", |
115 | | - # "message": "hi", |
116 | | - # "category": "myapp.models", |
117 | | -}) |
118 | | -``` |
119 | | - |
120 | | -The callback will only be called if a sentry client is configured. |
121 | | - |
122 | | - |
123 | | -## Concurrency |
124 | | - |
125 | | -* Sentry-Python currently does not support gevent-based setups. |
126 | | -* On ``init``, Sentry-Python spawns a thread on its own. That means if you use |
127 | | - ``uwsgi``, you currently need to enable threads. |
128 | | -* On Python 3.7, Sentry-Python supports and automatically uses ``ContextVars``. |
129 | | - This should effectively enable Sentry-Python to work with ``asyncio`` under |
130 | | - that Python version. |
131 | | - |
132 | | - |
133 | | -## PII |
134 | | - |
135 | | -Currently Sentry-Python does not send any personally-identifiable user data |
136 | | -with events by default. You need to explicitly enable this behavior with the |
137 | | -``send_default_pii`` option passed to ``init``: |
138 | | - |
139 | | -```python |
140 | | -init(..., send_default_pii=True) |
141 | | -``` |
142 | | - |
143 | | -## Integrations |
144 | | - |
145 | | -Head over to [the other pages](https://github.com/getsentry/sentry-python/tree/master/docs) |
146 | | -to check out integrations, which use these low-level APIs so you don't have to. |
| 15 | +Licensed under the MIT, see `LICENSE` |
0 commit comments