sentry-telegram - GitLite

KO | EN

gitlite — search

#typescript #llm #android #rust #macos #nodejs #windows #kubernetes #vue #awesome-list #pytorch #mcp #ios #open-source

sentry-telegram

(★ 283)

Plugin for Sentry which allows sending notification via Telegram messenger.

파일 탐색기

최종 버전 다운로드 (.zip)

- - python-publish.yml
- FUNDING.yml
- - telegram-window-dark.png
  - telegram-window-light.png
- _config.yml
- __init__.py
- plugin.py
- __init__.py
- conftest.py
- test_base.py
.coveragerc
.gitignore
.travis.yml
LICENSE
README.md
setup.py
tox.ini

# 설치 가이드

1. 코드 내려받기

git clone https://github.com/butorov/sentry-telegram

깃허브에서 프로젝트 코드 전체를 내 컴퓨터로 내려받습니다.

cd sentry-telegram

방금 내려받은 프로젝트 폴더 안으로 이동합니다.

2. 공식 설치 스크립트

쉬움 추천

사전 준비물

Python 3 pip 명령어를 쓰려면 Python이 필요합니다.

pip install sentry-telegram

PyPI에 배포된 패키지를 바로 설치합니다. 소스 클론이 필요 없습니다.

✅ 설치 후 새 터미널을 열고, 프로그램의 버전 확인 명령(예: --version)으로 정상 설치됐는지 확인하세요.

이 레포의 README에 적힌 실제 명령어를 그대로 가져왔습니다.

3. Python

쉬움

사전 준비물

Git GitHub에서 프로젝트 코드를 내려받으려면 필요합니다.
Python 3 설치 시 'Add Python to PATH' 옵션을 꼭 체크하세요 (Windows).

pip install sentry-telegram

PyPI에 배포된 패키지를 바로 설치합니다. 소스 클론이 필요 없습니다.

echo "pip install sentry-telegram" >> sentry/enhance-image.sh

requirements.txt 등에 명시된 파이썬 라이브러리를 설치합니다.

echo "pip install sentry-telegram==0.6.0" >> sentry/enhance-image.sh

requirements.txt 등에 명시된 파이썬 라이브러리를 설치합니다.

✅ 에러 메시지 없이 실행되고 터미널에 안내 문구가 출력되면 정상입니다.

이 레포의 README에 적힌 실제 명령어를 그대로 가져왔습니다.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Sentry Telegram ![Build Status](https://travis-ci.org/butorov/sentry-telegram.svg?branch=master) ![Coverage Status](https://codecov.io/gh/butorov/sentry-telegram/branch/master/graph/badge.svg) ![PyPI](https://badge.fury.io/py/sentry-telegram.svg) ![PyPI - Downloads](https://img.shields.io/pypi/dm/sentry-telegram)

Plugin for Sentry which allows sending notifications via the [Telegram](https://telegram.org/) messenger.

As any plugins installation is only available for [self-hosted Sentry](https://github.com/getsentry/self-hosted) instances, this plugin is unavailable for cloud-hosted [Sentry](https://sentry.io/).

The plugin has been tested with the most recent version of Sentry available at the time - 24.5.1.

# Features

- Sending notifications about issues to one or many Telegram users and/or groups.
- Sending notifications to particular threads (Topics) in chats.
- Customizable message template with placeholders for the project name, issue URL, title, error message, and tags.
- Support for Markdown formatting in the message template.
- Proxy support (through `origin_url` parameter in the configuration, see [#20](https://github.com/butorov/sentry-telegram/issues/20#issuecomment-483024745)).

# How will it look

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="/docs/images/telegram-window-dark.png">
  <source media="(prefers-color-scheme: light)" srcset="/docs/images/telegram-window-light.png">
  <img alt="How will it look" src="/docs/images/telegram-window-light.png">
</picture>

# Compatible versions

> **DISCLAIMER**: Sentry API is under development and is not frozen.
> I'm trying to keep up with the latest changes, but I can't guarantee compatibility with every version of Sentry. 
> If you have any issues, please create an [issue on GitHub](https://github.com/butorov/sentry-telegram/issues).

Table of compatibility:

| Plugin version | Compatible Sentry versions | Tested in Sentry versions                           |
|----------------|----------------------------|-----------------------------------------------------|
| 0.6.0          | 24.5.1, 24.6.x             | 24.5.1                                              |
| 0.5.0          | 24.4.x to 24.5.0           | 24.4.1, 24.4.2, 24.5.0                              |
| 0.4.0          | 8.x to 9.x                 | 8.9, 9.1.1                                          |
| 0.3.0          | 8.x to 9.x                 | 8.21, 8.22, 9.0.0, 9.1.0                            |
| 0.2.2          | 8.x to 9.x                 | 8.21, 8.22, 9.0.0                                   |
| 0.2.1          | 8.x to 9.x                 | 8.21, 8.22, 9.0.0                                   |
| 0.2.0          | 8.x                        | 8.9, 8.10, 8.11, 8.12, 8.13, 8.14, 8.15, 8.16, 8.17 |
| 0.1.2          | 8.x                        | 8.9.0, 8.12.0                                       |
| 0.1.1          | 8.x                        | 8.9.0                                               |

# Installation

> [!TIP]
> You can initiate the plugin installation both before and after setting up a Sentry instance.

1. On the host machine, where you have the [self-hosted Sentry repository](https://github.com/getsentry/self-hosted) cloned,
   copy `sentry/enhance-image.example.sh` file to `sentry/enhance-image.sh`:
   ```bash
   cp sentry/enhance-image.example.sh sentry/enhance-image.sh
   ```
2. Open `sentry/enhance-image.sh` file in your favorite text editor and add the following line to the end of the file:
   ```bash
   pip install sentry-telegram
   ```
   
   Or apply this command:
   ```bash
    echo "pip install sentry-telegram" >> sentry/enhance-image.sh
    ```
   
   So, the file will look like:
   ```bash
   #!/bin/bash
   # Enhance the base $SENTRY_IMAGE with additional dependencies, plugins - see https://github.com/getsentry/self-hosted#enhance-sentry-image
   # For example:
   # apt-get update
   # apt-get install -y gcc libsasl2-dev python-dev libldap2-dev libssl-dev
   # pip install python-ldap
   
   pip install sentry-telegram
   ```
   
   If you want to install a specific version of the plugin, you can specify it in the command (for example, version 0.6.0):
   ```bash
   echo "pip install sentry-telegram==0.6.0" >> sentry/enhance-image.sh
   ```
3. Run `./install.sh` script to build the Sentry image with the plugin installed:
   ```bash
   ./install.sh
   ```
4. After the script finishes, you can start the Sentry instance, or if it was already running, restart it.
   - For the first start, you need to run the following command:
     ```bash
     docker compose up -d
     ```
   - If the Sentry instance was already running, it's enough to restart several services:
     ```bash
     docker compose restart web worker cron sentry-cleanup
     ```

# Configuration

## Adding the plugin to a project

### From the Organization Settings

1. Go to your Sentry web interface. Open Settings page, that located in the left sidebar (`<your-sentry-installation-url>/settings/sentry/`).
2. In the "Organization" section of the second sidebar, go to the "Integrations" page (`<your-sentry-installation-url>/settings/sentry/integrations/`).
3. Find the "Telegram Notifications" plugin in the list of integrations and click on it.
4. Press the "Add to Project" button. You will be prompted to select a project to which you want to add the plugin (unless you have only one project).
5. You will be redirected to the plugin configuration page for the selected project.

### From the Project Settings

1. Go to your Sentry web interface. Open the Settings page of one of your projects (`<your-sentry-installation-url>/settings/sentry/projects/<project-name>/`).
2. In the second sidebar, go to the "Legacy Integrations" section (`<your-sentry-installation-url>/settings/sentry/projects/<project-name>/plugins/`).
3. Find the "Telegram Notifications" plugin in the list of integrations and select the "Configure plugin" link at the bottom of the plugin card.
4. Press the "Enable Plugin" button.

## Configuring the plugin

0. Assume you are on the plugin configuration page.
1. You need to create a Telegram bot to get the Bot API token. To do this, you need to talk to the [BotFather in Telegram](https://t.me/botfather).
   You can find more detailed instructions on how to create a bot in the [official Telegram documentation](https://core.telegram.org/bots/features#creating-a-new-bot).
2. After you have created a bot, copy the Bot API token and paste it into the "Bot API token" field on the plugin configuration page.
3. In the Receivers field, you need to specify the list of Telegram users and/or groups that will receive notifications.
   You can specify multiple receivers, each on a new line. You can use user/chat IDs, **but not usernames**.
   - To obtain the user ID, use can use one of the bots that can provide you with your user ID.
     For example, [this one](https://t.me/getmyid_bot) or [this one](https://t.me/raw_data_bot) (I don't have any relation to these bots) or any other, which you trust.
     Of course, you can use your own Bot API token to obtain the user ID.
   - To obtain the chat ID the easies way is to use "Share" button in the Telegram app and get the chat ID from the link.
     For example, if you share the chat with yourself, you will get the link like `https://t.me/c/123456789`.
     The chat ID in this case is `-123456789`.
     According to the Telegram Bot API requirements, you need to specify the chat ID with the minus sign (`-`) at the beginning.
   - If you have a chat with Topics, you can get the chat ID from the link as well. You need to share the particular Topic.
     For example, if you got a link `https://t.me/c/123456789/5`, the chat ID is `123456789` and the Topic ID is `5`.
     The receiver in this case will be `-123456789/5`.
   - Don't forget that all the receivers should allow the bot to send messages to them. 
     - For personal chats, it's enough to start a chat with the bot.
     - For groups, the bot should be added to the group and have a permission to send messages.
4. Set the "Message Template" as you want, or start with the default one.
   You can use the following placeholders in the message template:
   - `{project_name}` - the name of the project where the issue occurred.
   - `{url}` - the URL to the issue in the Sentry web interface.
   - `{title}` - the title of the issue.
   - `{message}` - the error message of the issue.
   - `tag[<tag_name>]` - the value of the tag with the name `<tag_name>`. For example, `tag[level]`. If the tag is not found, the placeholder will be replaced with `[NA]`.

Note that the Telegram message will be sent in Markdown format, so you can use Markdown formatting in the message template.
5. Press the "Save Changes" button.
6. Now you can test the plugin by pressing the "Test Plugin" button. You should receive a test message in the Telegram chat(s).
7. If you received the test message to Telegram and got `Test Results "No errors returned"` message at the top of the plugin configuration page, you are all set up!

> [!TIP]
> Don't forget to check the Sentry's alert rules to make sure that the Sentry will send notifications
for the events you want (new issues only, or all issues, etc.).

# Support This Project

If you find this project useful and would like to contribute financially, you can find several ways to do so on my [GitHub Sponsors page](https://github.com/sponsors/butorov).
Your support will assist in covering the costs of the servers used for testing the plugin and will serve as motivation for further improvements.

Your support is highly appreciated!