======
Sentry
======

.. 
   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
   !! This file is generated by oca-gen-addon-readme !!
   !! changes will be overwritten.                   !!
   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
   !! source digest: sha256:7923fe467a456494dd9d616d877a011ff438168f6c3bf24d94cecaeb8a9dcc7b
   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

.. |badge1| image:: https://img.shields.io/badge/maturity-Beta-yellow.png
    :target: https://odoo-community.org/page/development-status
    :alt: Beta
.. |badge2| image:: https://img.shields.io/badge/licence-AGPL--3-blue.png
    :target: http://www.gnu.org/licenses/agpl-3.0-standalone.html
    :alt: License: AGPL-3
.. |badge3| image:: https://img.shields.io/badge/github-OCA%2Fserver--tools-lightgray.png?logo=github
    :target: https://github.com/OCA/server-tools/tree/16.0/sentry
    :alt: OCA/server-tools
.. |badge4| image:: https://img.shields.io/badge/weblate-Translate%20me-F47D42.png
    :target: https://translation.odoo-community.org/projects/server-tools-16-0/server-tools-16-0-sentry
    :alt: Translate me on Weblate
.. |badge5| image:: https://img.shields.io/badge/runboat-Try%20me-875A7B.png
    :target: https://runboat.odoo-community.org/builds?repo=OCA/server-tools&target_branch=16.0
    :alt: Try me on Runboat

|badge1| |badge2| |badge3| |badge4| |badge5|

This module allows painless `Sentry <https://sentry.io/>`__ integration with
Odoo.

**Table of contents**

.. contents::
   :local:

Installation
============

The module can be installed just like any other Odoo module, by adding the
module's directory to Odoo *addons_path*. In order for the module to correctly
wrap the Odoo WSGI application, it also needs to be loaded as a server-wide
module. This can be done with the ``server_wide_modules`` parameter in your
Odoo config file or with the ``--load`` command-line parameter.

This module additionally requires the sentry-sdk Python package to be available on
the system. It can be installed using pip::

    pip install sentry-sdk

Configuration
=============

The following additional configuration options can be added to your Odoo
configuration file:

=============================  ====================================================================  ==========================================================
        Option                                          Description                                                         Default
=============================  ====================================================================  ==========================================================
``sentry_dsn``                 Sentry *Data Source Name*. You can find this value in your Sentry     ``''``
                               project configuration. Typically it looks something like this:
                               *https://<public_key>:<secret_key>@sentry.example.com/<project id>*
                               This is the only required option in order to use the module.

``sentry_enabled``             Whether or not Sentry logging is enabled.                             ``False``

``sentry_logging_level``       The minimal logging level for which to send reports to Sentry.        ``warn``
                               Possible values: *notset*, *debug*, *info*, *warn*, *error*,
                               *critical*. It is recommended to have this set to at least *warn*,
                               to avoid spamming yourself with Sentry events.

``sentry_exclude_loggers``     A string of comma-separated logger names which should be excluded     ``werkzeug``
                               from Sentry.

``sentry_ignored_exceptions``  A string of comma-separated exceptions which should be ignored.       ``odoo.exceptions.AccessDenied,
                               You can use a star symbol (*) at the end, to ignore all exceptions    odoo.exceptions.AccessError,
                               from a module, eg.: *odoo.exceptions.**.                              odoo.exceptions.DeferredException,
                                                                                                     odoo.exceptions.MissingError,
                                                                                                     odoo.exceptions.RedirectWarning,
                                                                                                     odoo.exceptions.UserError,
                                                                                                     odoo.exceptions.ValidationError,
                                                                                                     odoo.exceptions.Warning,
                                                                                                     odoo.exceptions.except_orm``

``sentry_include_context``     If enabled, additional context data will be extracted from current    ``True``
                               HTTP request and user session (if available). This has no effect
                               for Cron jobs, as no request/session is available inside a Cron job.

``sentry_release``             Explicitly define a version to be sent as the release version to
                               Sentry. Useful in conjuntion with Sentry's "Resolve in the next
                               release"-functionality. Also useful if your production deployment
                               does not include any Git context from which a commit might be read.
                               Overrides *sentry_odoo_dir*.

``sentry_odoo_dir``            Absolute path to your Odoo installation directory. This is optional
                               and will only be used to extract the Odoo Git commit, which will be
                               sent to Sentry, to allow to distinguish between Odoo updates.
                               Overridden by *sentry_release*
=============================  ====================================================================  ==========================================================

Other `client arguments
<https://docs.sentry.io/platforms/python/configuration/>`_ can be
configured by prepending the argument name with *sentry_* in your Odoo config
file. Currently supported additional client arguments are: ``with_locals,
max_breadcrumbs, release, environment, server_name, shutdown_timeout,
in_app_include, in_app_exclude, default_integrations, dist, sample_rate,
send_default_pii, http_proxy, https_proxy, request_bodies, debug,
attach_stacktrace, ca_certs, propagate_traces, traces_sample_rate,
auto_enabling_integrations``.

Example Odoo configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~

Below is an example of Odoo configuration file with *Odoo Sentry* options::

    [options]
    sentry_dsn = https://<public_key>:<secret_key>@sentry.example.com/<project id>
    sentry_enabled = true
    sentry_logging_level = warn
    sentry_exclude_loggers = werkzeug
    sentry_ignore_exceptions = odoo.exceptions.AccessDenied,
        odoo.exceptions.AccessError,odoo.exceptions.MissingError,
        odoo.exceptions.RedirectWarning,odoo.exceptions.UserError,
        odoo.exceptions.ValidationError,odoo.exceptions.Warning,
        odoo.exceptions.except_orm
    sentry_include_context = true
    sentry_environment = production
    sentry_release = 1.3.2
    sentry_odoo_dir = /home/odoo/odoo/

Usage
=====

Once configured and installed, the module will report any logging event at and
above the configured Sentry logging level, no additional actions are necessary.

.. image:: https://odoo-community.org/website/image/ir.attachment/5784_f2813bd/datas
   :alt: Try me on Runbot
   :target: https://runbot.odoo-community.org/runbot/149/14.0

Known issues / Roadmap
======================

* **No database separation** -- This module functions by intercepting all Odoo
  logging records in a running Odoo process. This means that once installed in
  one database, it will intercept and report errors for all Odoo databases,
  which are used on that Odoo server.

* **Frontend integration** -- In the future, it would be nice to add
  Odoo client-side error reporting to this module as well, by integrating
  `raven-js <https://github.com/getsentry/raven-js>`_. Additionally, `Sentry user
  feedback form <https://docs.sentry.io/learn/user-feedback/>`_ could be
  integrated into the Odoo client error dialog window to allow users shortly
  describe what they were doing when things went wrong.

Bug Tracker
===========

Bugs are tracked on `GitHub Issues <https://github.com/OCA/server-tools/issues>`_.
In case of trouble, please check there if your issue has already been reported.
If you spotted it first, help us to smash it by providing a detailed and welcomed
`feedback <https://github.com/OCA/server-tools/issues/new?body=module:%20sentry%0Aversion:%2016.0%0A%0A**Steps%20to%20reproduce**%0A-%20...%0A%0A**Current%20behavior**%0A%0A**Expected%20behavior**>`_.

Do not contact contributors directly about support or help with technical issues.

Credits
=======

Authors
~~~~~~~

* Mohammed Barsi
* Versada
* Nicolas JEUDY
* Vauxoo

Contributors
~~~~~~~~~~~~

* Mohammed Barsi <barsintod@gmail.com>
* Andrius Preimantas <andrius@versada.eu>
* Naglis Jonaitis <naglis@versada.eu>
* Atte Isopuro <atte.isopuro@avoin.systems>
* Florian Mounier <florian.mounier@akretion.com>
* Jon Ashton <jon@monkeyinferno.com>
* Mark Schuit <mark@gig.solutions>

Other credits
~~~~~~~~~~~~~

* Vauxoo

Maintainers
~~~~~~~~~~~

This module is maintained by the OCA.

.. image:: https://odoo-community.org/logo.png
   :alt: Odoo Community Association
   :target: https://odoo-community.org

OCA, or the Odoo Community Association, is a nonprofit organization whose
mission is to support the collaborative development of Odoo features and
promote its widespread use.

.. |maintainer-barsi| image:: https://github.com/barsi.png?size=40px
    :target: https://github.com/barsi
    :alt: barsi
.. |maintainer-naglis| image:: https://github.com/naglis.png?size=40px
    :target: https://github.com/naglis
    :alt: naglis
.. |maintainer-versada| image:: https://github.com/versada.png?size=40px
    :target: https://github.com/versada
    :alt: versada
.. |maintainer-moylop260| image:: https://github.com/moylop260.png?size=40px
    :target: https://github.com/moylop260
    :alt: moylop260
.. |maintainer-fernandahf| image:: https://github.com/fernandahf.png?size=40px
    :target: https://github.com/fernandahf
    :alt: fernandahf

Current `maintainers <https://odoo-community.org/page/maintainer-role>`__:

|maintainer-barsi| |maintainer-naglis| |maintainer-versada| |maintainer-moylop260| |maintainer-fernandahf| 

This module is part of the `OCA/server-tools <https://github.com/OCA/server-tools/tree/16.0/sentry>`_ project on GitHub.

You are welcome to contribute. To learn how please visit https://odoo-community.org/page/Contribute.
