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

#185426444 Readme headline normalization, clarification, and expansion of docs #6

Merged
merged 1 commit into from
Jun 28, 2023
Merged

#185426444 Readme headline normalization, clarification, and expansion of docs #6

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
59 changes: 31 additions & 28 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,12 +2,12 @@

The Moesif Envoy WebAssembly plugin captures API traffic from [Envoy Service Proxy](https://www.envoyproxy.io/) and logs it to [Moesif API Analytics](https://www.moesif.com). This plugin leverages an asynchronous design and doesn’t add any latency to your API calls.

- Envoy is an open-source Service Proxy.
- Moesif is an API analytics and monitoring service.
- Envoy is an L7 proxy and communication bus.
- Moesif is an API analytics and monetization platform.

[Source Code on GitHub](https://github.com/Moesif/moesif-envoy-wasm-plugin)

## Installation Instructions
## How to Install

### 1. Download the Plugin

Expand All @@ -28,7 +28,7 @@ Update your Envoy configuration (`envoy.yaml`) to use the Moesif Envoy plugin. A

Remember to replace `<YOUR APPLICATION ID HERE>` with your actual Moesif Application Id. Your Moesif Application Id can be found in the [_Moesif Portal_](https://www.moesif.com/). After signing up for a Moesif account, your Moesif Application Id will be displayed during the onboarding steps.

The upstream config defaults to 'moesif_api', but if you use something else in the clusters.name field, you will need to explicitly include the base_uri to match.
The `upstream` config defaults to 'moesif_api' and is optional, but if you use something else in the clusters.name field, you will need to explicitly include the `upstream` config value to match.

Also, remember to update the filename path in the `vm_config` section to match the location where you placed the `moesif_envoy_wasm_plugin.wasm` file.

Expand Down Expand Up @@ -62,7 +62,7 @@ http_filters:
clusters:
# ... other clusters ...
- name: moesif_api
type: logical_dns
type: strict_dns
load_assignment:
cluster_name: moesif_api
endpoints:
Expand All @@ -75,7 +75,7 @@ clusters:
transport_socket:
name: envoy.transport_sockets.tls
typed_config:
"@type": type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.UpstreamTlsContext
"@type": type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.UpstreamTlsContext"
Copy link

@praves77 praves77 Jun 28, 2023 •
edited
Loading

Choose a reason for hiding this comment

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

@bakennedy I'm seeing extra " above.

```

### 4. Restart Envoy
Expand All @@ -86,6 +86,18 @@ After saving the updated configuration file, restart Envoy to apply the changes.

Make a few API calls that pass through the Envoy proxy. These calls should now be logged to your Moesif account.

## How to Use

### Capturing API traffic
The Moesif Envoy plugin captures API traffic from Envoy and logs it to Moesif automatically when Envoy routes traffic through the plugin. Envoy has detailed and robust configuration options for traffic and plugin routing to apply the Moesif plugin to only some traffic or to all traffic. For more information, please refer to the [Envoy Request Lifecycle Guide](https://www.envoyproxy.io/docs/envoy/latest/intro/life_of_a_request#configuration).

### Identifying users and companies

This plugin will automatically identify API users so you can associate API traffic to web traffic and create cross-platform funnel reports of your customer journey. The plugin currently supports reading request headers to identify users and companies automatically from events.

- If the `user_id_header` or `company_id_header` configuration option is set, the named request header will be read from each request and it's value will be included in the Moesif event model as the `user_id` or `company_id` field respectively.
2. You can associate API users to companies for tracking account-level usage. This can be done either with the company header above or through the Moesif [update user API](https://www.moesif.com/docs/api#update-a-user) to set a `company_id` for a user. Moesif will associate the API calls automatically.

## Configuration Options

These configuration options are specified as JSON in the `configuration` section of the `http_filters` in your `envoy.yaml` file.
Expand All @@ -95,9 +107,9 @@ These configuration options are specified as JSON in the `configuration` section
| `moesif_application_id`| String | None | **Required.** Your Moesif Application Id. Can be found within the Moesif Portal. |
| `user_id_header` | String | None | Optional. The header key for User Id. If provided, the corresponding header value is used as the User Id in Moesif event models. |
| `company_id_header` | String | None | Optional. The header key for Company Id. If provided, the corresponding header value is used as the Company Id in Moesif event models. |
| `batch_max_size` | usize | 10 | Optional. The maximum batch size of events to be sent to Moesif. |
| `batch_max_wait` | usize | 2 | Optional. The maximum wait time in seconds before a batch is sent to Moesif, regardless of the batch size. |
| `upstream` | String | "moesif_api" | Optional. The upstream cluster that points to Moesif's API. |
| `batch_max_size` | Integer | 10 | Optional. The maximum batch size of events to be sent to Moesif. |
| `batch_max_wait` | Integer | 2 | Optional. The maximum wait time in seconds before a batch is sent to Moesif, regardless of the batch size. |
| `upstream` | String | "moesif_api" | Optional. The upstream cluster in Envoy that points to Moesif's API. |

### Example

Expand All @@ -109,13 +121,19 @@ configuration:
"moesif_application_id":"<YOUR APPLICATION ID HERE>",
"user_id_header":"X-User-Example-Header",
"company_id_header":"X-Company-Example-Header",
"batch_max_size": 20,
"batch_max_wait": 3,
"batch_max_size": 100,
"batch_max_wait": 5,
"upstream": "example_custom_envoy_cluster_naming_scheme_moesif"
}
```

## Docker Compose Instructions
### Updating the Configuration

Updating the envoy.yaml configuration file in the example above and restarting is sufficient to update your Moesif WASM Plugin configuration. Envoy has a diversity of configuration mechanisms and supports hot reloading of configuration. For more information, please refer to the [Envoy Configuration Documentation](https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/operations/dynamic_configuration).

## Examples

### Envoy Docker Compose

If you're using Docker, you can use the provided `docker-compose.yaml` to easily set up your environment. The Docker Compose file includes three services:

Expand All @@ -130,7 +148,7 @@ If you're using Docker, you can use the provided `docker-compose.yaml` to easily

```bash
git clone https://github.com/Moesif/moesif-envoy-wasm-plugin.git
cd moesif-envoy-plugin
cd moesif-envoy-plugin/examples/envoy
```

3. Build and start the services using Docker Compose.
Expand All @@ -139,8 +157,6 @@ If you're using Docker, you can use the provided `docker-compose.yaml` to easily
docker-compose up --build
```

The `--build` flag ensures that the `rust-builder` service is built before starting the other services.

4. Now, you can send requests to `http://localhost:10000`. The Envoy proxy listens on this port, forwards the requests to the echo server, and logs the requests and responses to Moesif.

5. You can view the Envoy logs with the following command:
Expand All @@ -151,19 +167,6 @@ If you're using Docker, you can use the provided `docker-compose.yaml` to easily

Remember to replace `<YOUR APPLICATION ID HERE>` in `envoy.yaml` file with your actual Moesif Application Id. Your Moesif Application Id can be found in the [_Moesif Portal_](https://www.moesif.com/).

```bash
docker-compose down
docker-compose up --build
```

### Configuration Options

For a comprehensive list of configuration options, refer to the 'Configuration options' section.

## How to Test

Configure Envoy to use the Moesif Envoy plugin. Make a few API calls that pass through the Envoy proxy. These calls should now be logged to your Moesif account.

## Other Integrations

To view more documentation on integration options, please visit __[the Integration Options Documentation](https://www.moesif.com/docs/getting-started/integration-options/).__
2 changes: 1 addition & 1 deletion examples/envoy/envoy.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -67,7 +67,7 @@ static_resources:
address: echo
port_value: 5678
- name: moesif_api
type: logical_dns
type: strict_dns
dns_refresh_rate: 500s
load_assignment:
cluster_name: moesif_api
Expand Down