View Source Agent Quick Install
introduction
Introduction
This is a concise list of steps to install the Paraxial.io agent. It is intended for users who have already read the agent guide.
1-mix-install
1. Mix install
{:paraxial, "~> 1.1.0"}
2-config
2. Config
config :paraxial,
paraxial_api_key: System.get_env("PARAXIAL_API_KEY"), # Required
paraxial_url: "https://app.paraxial.io", # Required
fetch_cloud_ips: true, # Optional, default is false
bulk: %{email: %{trusted: 100, untrusted: 3}}, # Optional, see https://hexdocs.pm/paraxial/Paraxial.html#functions
trusted_domains: MapSet.new(["paraxial.io", "blackcatprojects.xyz"]) # Optional, see https://hexdocs.pm/paraxial/Paraxial.html#functions
Set the PARAXIAL_API_KEY
environment variable to keep this secret out of source code.
3-edit-endpoint-ex
3. Edit endpoint.ex
plug RemoteIp
plug Paraxial.AllowedPlug
plug Paraxial.RecordPlug
plug HavanaWeb.Router
plug Paraxial.RecordPlug
4-optional-to-send-current-user-edit-router-ex-add-paraxial-currentuserplug
4. (Optional) To send current user, edit router.ex
, add Paraxial.CurrentUserPlug
defmodule HavanaWeb.Router do
...
pipeline :browser do
...
plug Paraxial.CurrentUserPlug
end
Note: Only works with assign(conn, :paraxial_current_user, conn.assigns.current_user.email)
5-optional-send-paraxial_login_user_name-via-assigns
5. (Optional) Send :paraxial_login_user_name
via assigns
In your application code, determine how a user's login attempt flows through the code. You are looking for the line right before the user's provided email and password are checked against the database. Once you find that location, re-write the conn with:
conn = assign(conn, :paraxial_login_user_name, email)
Where email
is the user provided string for a login attempt.
6-optional-send-login-success-true-or-false
6. (Optional) Send login success true or false
conn = assign(conn, :paraxial_login_success, false)
7-optional-use-the-paraxial-bulk_allowed-3-function
7. (Optional) Use the Paraxial.bulk_allowed?/3
function
In your Paraxial.io config, you can define :bulk
and :trusted_domains
bulk: %{email: %{trusted: 100, untrusted: 3}},
trusted_domains: MapSet.new(["paraxial.io", "blackcatprojects.xyz"])
In your application code,
Paraxial.bulk_allowed?(user.email, :email, length(list_of_emails))
will return true or false, depending on the value of the third argument (an integer), and if the email matching a trusted domain.
8-optional-configure-the-agent-to-only-send-events-for-specific-routes
8. (Optional) Configure the agent to only send events for specific routes
To only collect data for specific routes, set your configuration at compile time to the code below, by editing your config/dev.exs
, config/test.exs
, and config/prod.exs
files.
Do NOT set only:
or except:
at runtime, the agent uses metaprogramming to generate code at compile time. If you set only:
or except:
at runtime, the agent will ignore the config and send data for all routes.
To have the agent only send data to the backend for the following:
- GET /users/log_in
- POST /users/log_in
- GET /users/:id/settings
config :paraxial,
paraxial_api_key: System.get_env("PARAXIAL_API_KEY"),
paraxial_url: "https://app.paraxial.io",
...
only: [
%{path: "/users/log_in", method: "GET"},
%{path: "/users/log_in", method: "POST"}
%{path: "/users/:id/settings", method: "POST"}
]
To send events for all routes, except the following:
- GET /health_check
- GET /users/:id/status
config :paraxial,
paraxial_api_key: System.get_env("PARAXIAL_API_KEY"),
paraxial_url: "https://app.paraxial.io",
...
except: [
%{path: "/health_check", method: "GET"}
%{path: "/users/:id/status", method: "GET"}
]
If this change does not work in your local development environment, run:
MIX_ENV=dev mix deps.compile --force paraxial
9-optional-configure-the-agent-to-exclude-events-for-specific-routes
9. (Optional) Configure the agent to exclude events for specific routes
To have the agent send data to the backend for all routes, except certain ones:
- GET /health_check
Set your config to:
config :paraxial,
paraxial_api_key: System.get_env("PARAXIAL_API_KEY"),
paraxial_url: "https://app.paraxial.io",
...
except: [
%{path: "/users/health_check", method: "GET"}
]