Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Postfix rewrite #16724

Merged
merged 3 commits into from
Apr 1, 2024
Merged

Postfix rewrite #16724

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
93797d1
First draft of rewrite
bradleycamacho Mar 25, 2024
9df601d
Apply feedback
bradleycamacho Apr 1, 2024
1156518
Fix indents
bradleycamacho Apr 1, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
113 changes: 46 additions & 67 deletions ...ure/host-integrations/host-integrations-list/postfix-monitoring-integration.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ tags:
- Postfix integration
- New Relic integrations
metaDescription: Use New Relics infrastructure agent to get a dashboard with metrics from your Postfix application.
freshnessValidatedDate: 2023-06-28
freshnessValidatedDate: 2024-03-25
---

import infrastructurePostfixDashboard from 'images/infrastructure_screenshot-full_Postfix-dashboard.webp'
Expand All @@ -23,83 +23,65 @@ After setting up our Postfix integration, we give you a dashboard for your Postf
</figcaption>


## Install the infrastructure agent [#infra]

To get data into New Relic, install our infrastructure agent. Our infrastructure agent collects and ingests data so you can keep track of your mail server's performance. The version should be 1.10.7 or higher to support NRI-Flex integration.

You can install the infrastructure agent two different ways:

* Our [guided install](https://one.newrelic.com/nr1-core?state=4f81feab-35f7-e97e-9903-52510f8542bd) is a CLI tool that inspects your system and installs the infrastructure agent alongside the application monitoring agent that best works for your system. To learn more about how our guided install works, check out our [Guided install overview](/docs/infrastructure/host-integrations/installation/new-relic-guided-install-overview).
* If you'd rather install our infrastructure agent manually, you can follow a tutorial for manual installation for [Linux](/docs/infrastructure/install-infrastructure-agent/linux-installation/install-infrastructure-monitoring-agent-linux), [Windows](/docs/infrastructure/install-infrastructure-agent/windows-installation/install-infrastructure-monitoring-agent-windows/), or [macOS](/docs/infrastructure/install-infrastructure-agent/macos-installation/install-infrastructure-monitoring-agent-macos/).
## Set up the Postfix integration
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Intro reads a little awkward but it's not letting edit in GH:

Our Postfix integration consolidates mail server data into one view, so you can track how many emails are sent, bounced, or deferred in a given time period. Our Postfix integration uses our infrastructure monitoring agent, and gives you a pre-built dashboard with your most important Postfix metrics like email delivery process, mail queue, and message overview.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

idk edit this so its smoother or just take it. "performance metrics" for a mail server felt a little stilted

Complete the following steps to set up the Postfix integration:

<Steps>
<Step>
## Install the infrastructure agent [#infra-install]

To use the Postfix integration, you need to also [install the infrastructure agent](/docs/infrastructure/install-infrastructure-agent/get-started/install-infrastructure-agent-new-relic/) on the same host. The infrastructure agent monitors the host itself, while the integration you'll install in the next step extends your monitoring with Postfix-specific data.
</Step>
<Step>
## Export Postfix data [#export]

Use `pflogsumm` to export your Postfix metrics. `Pflogsumm` is a log analyzer for Postfix agent and designed to provide an overview of Postfix activity, with just enough detail to give the administrator a "heads up" for potential trouble spots.
Use `pflogsumm` to export your Postfix metrics. `Pflogsumm` is a log analyzer for Postfix agent and designed to provide an overview of Postfix activity, with enough detail to give the administrator a "heads up" for potential trouble spots.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Use `pflogsumm` to export your Postfix metrics. `Pflogsumm` is a log analyzer for Postfix agent and designed to provide an overview of Postfix activity, with enough detail to give the administrator a "heads up" for potential trouble spots.
Export your Postfix metrics with `pflogsumm`. The Postfix agent uses`pflogsumm` as a log analyzer, which translates into metric data about your Postfix activity. This gives you enough detail to anticipate potential incidences with email administration.


Follow these steps to use `pflogsumm`.

<CollapserGroup>
<Collapser
className="freq-link"
id="export"
title={<>Download <InlineCode>pflogsumm</InlineCode></>}
>
1. Run the following command to use `pflogsumm`:
1. Run the following commands to download and extract `pflogsumm`:
Copy link
Contributor

@akristen akristen Mar 29, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do they need to be in a particular directory/folder/whatever?


```shell
wget https://jimsun.linxnet.com/downloads/pflogsumm-1.1.3.tar.gz
```

2. Extract the downloaded file.

```shell
tar xvf pflogsumm-1.1.3.tar.gz
```

3. Navigate to the `pflogsumm` folder.
2. Navigate to the `pflogsumm` folder.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
2. Navigate to the `pflogsumm` folder.
2. Go to the `pflogsumm` folder.


```shell
cd pflogsumm-*.*.*
```
4. Copy the `pflogsumm.pl` file to the path `/usr/local/bin/pflogsumm` :

3. Copy the `pflogsumm.pl` file to the path `/usr/local/bin/pflogsumm` :

```shell
sudo cp pflogsumm.pl /usr/local/bin/pflogsumm
```

</Collapser>

<Collapser
className="freq-link"
id="export"
title={<>Run <InlineCode>pflogsumm</InlineCode> commands to get the Postfix metrics</>}
>
4. Run the following `pflogsumm` commands to export the Postfix metrics:

```shell
cat /var/log/mail.log | pflogsumm
cat /var/log/mail.log | pflogsumm -d today
```

</Collapser>
</CollapserGroup>


```
</Step>
<Step>
## Configure NRI-Flex for Postfix

Flex comes bundled with the New Relic infrastructure agent. To create a flex configuration file follow these steps:
Flex, our application-agnostic monitoring tool, comes bundled with the New Relic infrastructure agent. To create a flex configuration file to report Postfix data follow these steps:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

do we have an app-gnostic tool 😏

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Flex, our application-agnostic monitoring tool, comes bundled with the New Relic infrastructure agent. To create a flex configuration file to report Postfix data follow these steps:
Flex, our application-agnostic monitoring tool, comes bundled with the New Relic infrastructure agent. Follow these steps to create a flex configuration file for your Postfix data:


1. Create a file named `postfix-flex-config.yml` in this path:
1. Create a file named `postfix-flex-config.yml`:

```shell
/etc/newrelic-infra/integrations.d
touch /etc/newrelic-infra/integrations.d/postfix-flex-config.yml
```

2. Update the file `postfix-flex-config.yml` with these configurations:
* `EVENT_TYPE`: You can consider `EVENT_TYPE` as a New Relic database table that you can query using NRQL.
* `COMMAND`: This contains the command which is used to print metrics on the terminal.

Once your configuration file is updated, it will look like below:
2. Update the file `postfix-flex-config.yml`. You can use the configuration sample below, or create your own using the following pattern:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should reorganize this step. Let me give it a stab

Copy link
Contributor

@akristen akristen Mar 29, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
2. Update the file `postfix-flex-config.yml`. You can use the configuration sample below, or create your own using the following pattern:
2. Update the file `postfix-flex-config.yml`. We recommend you work off our configuration sample below:
EXAMPLE HERE
If you'd prefer to make your own, then make sure that your yaml file follows this pattern:
```yml
- event_type: A New Relic database table that you can query using NRQL.
commands: The command used to print metrics on the terminal.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

although frankly i think this is even too verbose. customers can just refer to our provided snippet but the "make your own instructions" should prob just be AFTER the example with the explanations for the value they need to put in

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

also indent this

* `EVENT_TYPE`: A New Relic database table that you can query using NRQL.
* `COMMAND`: The command used to print metrics on the terminal.

```yml
---
Expand Down Expand Up @@ -332,42 +314,40 @@ Flex comes bundled with the New Relic infrastructure agent. To create a flex con
set_header: [Bounce.msgCount, bounceMessage]
regex_match: true
split_by: \s*(\d+)\s\s\s(.*.)
```


```
</Step>
<Step>
## Forward your Postfix logs to New Relic

You can use our [log forwarding](/docs/logs/forward-logs/forward-your-logs-using-infrastructure-agent/) to forward Postfix logs to New Relic.

On Linux machines, your log file named `logging.yml` should be present in this path:
1. Create a file named `logging.yml` in the infrastrucutre agent directory:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

same comment as sonarqube. what value do customers get by forwarding logs? how does opting out of log forwarding degrade their data?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'll add a quick intro sentence, but I don't think we should delve into explaining the big "whys" and "hows" of logs. I think it is outside the scope of an intro experience, and getting users an experience with as much data as possible is the priority.


```shell
/etc/newrelic-infra/logging.d/
touch /etc/newrelic-infra/logging.d/logging.yml
```

After creating the log file, add the following script to the `logging.yml` file:
2. Add the following snippet to the `logging.yml` file:

```yml
logs:
- name: mail.log
file: /var/log/mail.log
attributes:
logtype: postfix_maillog
```
```
</Step>
<Step>
## Restart the infrastructure agent [#restart-infra]

## Restart the New Relic infrastructure agent

Before you can start reading your data, use the instructions in our [infrastructure agent docs](/docs/infrastructure/install-infrastructure-agent/manage-your-agent/start-stop-restart-infrastructure-agent/) to restart your infrastructure agent.
Use the instructions in our [infrastructure agent docs](/docs/infrastructure/install-infrastructure-agent/manage-your-agent/start-stop-restart-infrastructure-agent/) to restart your infrastructure agent. This is a basic command that should work for most people:

```shell
sudo systemctl restart newrelic-infra.service
```
In couple of minutes, your application will send metrics to [one.newrelic.com](https://one.newrelic.com).


```
</Step>
<Step>
## Monitor your application

You can choose our pre-built dashboard template named `Postfix` to monitor your Postfix application metrics. Follow these steps to use our pre-built dashboard template:
Follow these steps to use our pre-built dashboard template to easily view your Postfix data:

1. Go to <DoNotTranslate>**[one.newrelic.com](https://one.newrelic.com/)**</DoNotTranslate> and click on <DoNotTranslate>**+ Add data**</DoNotTranslate>.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

i'm just noticing this, but should these substeps be nested? i would go back and check sonarqube to make sure they are as well

2. Click on the <DoNotTranslate>**Dashboards**</DoNotTranslate> tab.
Expand All @@ -376,28 +356,27 @@ You can choose our pre-built dashboard template named `Postfix` to monitor your

Your Postfix dashboard is considered a custom dashboard and can be found in the <DoNotTranslate>**Dashboards**</DoNotTranslate> UI. For docs on using and editing dashboards, see [our dashboard docs](/docs/query-your-data/explore-query-data/dashboards/introduction-dashboards).
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would spruce this step up and make it a 'View your data' pattern per other OHIs. I also don't think we should err on the side of linking out to docs in branching oHI steps bc it gets tedious + might deter customers from getting any value from it


Here is a NRQL query to view your latest message record's status:
Here's a few example NRQL queries for Postfix data:

View your latest message record's status
```sql
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

indent

SELECT *
FROM PostfixGrandTotals
```


Here is a NRQL query to view your per-hour message records:

View your per-hour message records
```sql
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

indent

SELECT *
FROM PostfixMessagePerHourReport
```

```
</Step>
</Steps>

## What's next?

To learn more about building NRQL queries and generating dashboards, check out these docs:

* [Introduction to the query builder](/docs/query-your-data/explore-query-data/query-builder/introduction-query-builder) to create basic and advanced queries.
* [Introduction to dashboards](/docs/query-your-data/explore-query-data/dashboards/introduction-dashboards) to customize your dashboard and carry out different actions.
* [Manage your dashboard](/docs/query-your-data/explore-query-data/dashboards/manage-your-dashboard) to adjust your <InlinePopover type="dashboards" /> display mode, or to add more content to your dashboard.


* [Manage your dashboard](/docs/query-your-data/explore-query-data/dashboards/manage-your-dashboard) to adjust your <InlinePopover type="dashboards" /> display mode, or to add more content to your dashboard.
Loading