From c2fc684844e462785f16648dbaaed50e1da8850f Mon Sep 17 00:00:00 2001 From: Angelo Breuer Date: Fri, 1 Sep 2023 10:07:22 +0200 Subject: [PATCH] docs: Add cluster docs --- docs/docs/cluster/best-practices.md | 5 ---- docs/docs/cluster/failover.md | 5 ---- docs/docs/cluster/getting-started.md | 41 +++++++++++++++++++++++++++ docs/docs/cluster/introduction.md | 14 ++++++++++ docs/docs/cluster/load-balancing.md | 5 ---- docs/docs/cluster/track-affinity.md | 42 ++++++++++++++++++++++++++++ 6 files changed, 97 insertions(+), 15 deletions(-) delete mode 100644 docs/docs/cluster/best-practices.md delete mode 100644 docs/docs/cluster/failover.md create mode 100644 docs/docs/cluster/getting-started.md delete mode 100644 docs/docs/cluster/load-balancing.md diff --git a/docs/docs/cluster/best-practices.md b/docs/docs/cluster/best-practices.md deleted file mode 100644 index 4f715341..00000000 --- a/docs/docs/cluster/best-practices.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -sidebar_position: 2 ---- - -# Best practices diff --git a/docs/docs/cluster/failover.md b/docs/docs/cluster/failover.md deleted file mode 100644 index f6dbc8dc..00000000 --- a/docs/docs/cluster/failover.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -sidebar_position: 5 ---- - -# Automatic failover \ No newline at end of file diff --git a/docs/docs/cluster/getting-started.md b/docs/docs/cluster/getting-started.md new file mode 100644 index 00000000..6edb5513 --- /dev/null +++ b/docs/docs/cluster/getting-started.md @@ -0,0 +1,41 @@ +--- +sidebar_position: 2 +--- + +# Getting Started + +Now that we are clear to start, we only need to prepare a single thing before starting assuming you already have multiple lavalink nodes at hand. + +## Installation + +First, we need to install the `Lavalink4NET.Cluster` package. You can do this by using the following command: + +```bash +dotnet add package Lavalink4NET.Cluster +``` + +Alternatively, use the NuGet package manager in your IDE, if you are using one. + +## Configuration + +Now that we have installed the package, we need to configure it. There is not much difference between the single node audio service and the clustered one. You will only need to make changes in a few points. We start by adding the clustered audio service: + +```csharp +// Replace this with your call to AddLavalink() +builder.Services.AddLavalinkCluster(); + +// Replace this with your call to ConfigureLavalink() +builder.Services.ConfigureLavalinkCluster(x => +{ + x.Nodes = ImmutableArray.Create( + new LavalinkClusterNodeOptions { BaseAddress = new Uri("http://localhost:2333/"), }, + new LavalinkClusterNodeOptions { BaseAddress = new Uri("http://localhost:2334/"), }, + new LavalinkClusterNodeOptions { BaseAddress = new Uri("http://localhost:2335/"), }); +}); +``` + +In your application itself, you don't really need to make any changes besides that. Now you are ready to go and can start using the clustered audio service. + +:::info +You can also assign your nodes a label to identify them while debugging or in logs. You can do this by setting the `Label` property on the `LavalinkClusterNodeOptions` object. +::: \ No newline at end of file diff --git a/docs/docs/cluster/introduction.md b/docs/docs/cluster/introduction.md index 4a9105c5..9c71fb33 100644 --- a/docs/docs/cluster/introduction.md +++ b/docs/docs/cluster/introduction.md @@ -3,3 +3,17 @@ sidebar_position: 1 --- # Introduction + +Clusters are a great way to improve the load balancing and availability of your application. They are also a great way to scale your application horizontally. In this guide, we will learn how to create a lavalink node cluster. + +## When do I need clustering? + +Clustering makes sense when you have a large number of users and you want to distribute the load across multiple nodes. Lavalink can start to consume huge resources when you have a lot of users using the music feature. In case, a single server is unable to load, you can start by utilizing multiple nodes distributed on different dedicates servers to handle the load. + +## When I don't need clustering? + +If you are running a small bot with a few users, you don't need to use clustering. Clustering is only useful when you have a large number of users. Nearly all bots are able to run on a single node without any issues. If you are running a large bot, you can start by using a single node and then scale to multiple nodes when you need it. Lavalink4NET recommends to start with using no clustering when you first once created your bot. Only use clustering if your needs become a requirement since clustering for small bots introduced a lot of complexity and is mostly considered premature optimization for small bots. + +## How does clustering work? + +To use clustering you need a set of highly available lavalink nodes. Those nodes are registered while configuring Lavalink4NET. Lavalink4NET will start off by using the first node if needed. Once more players are utilized, Lavalink4NET will start using the other nodes. Lavalink4NET will automatically distribute the load across all nodes. If a node is unavailable, Lavalink4NET will automatically detect the node as degraded and will stop using it. Once the node is available again, Lavalink4NET will automatically start using it again. This makes it possible to have a highly available lavalink cluster. diff --git a/docs/docs/cluster/load-balancing.md b/docs/docs/cluster/load-balancing.md deleted file mode 100644 index 34c4ea55..00000000 --- a/docs/docs/cluster/load-balancing.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -sidebar_position: 4 ---- - -# Load balancing diff --git a/docs/docs/cluster/track-affinity.md b/docs/docs/cluster/track-affinity.md index 572629c4..d35d1cb5 100644 --- a/docs/docs/cluster/track-affinity.md +++ b/docs/docs/cluster/track-affinity.md @@ -3,3 +3,45 @@ sidebar_position: 3 --- # Track affinity + +Track affinity is an optimization that is available when using clustering with Lavalink4NET. By default, if no information is provided, Lavalink4NET will use any available node in the cluster to resolve a track. You can configure Lavalink4NET to use a specific node to resolve a track which can improve performance in some cases. + +## How to use track affinity + +Lavalink4NET provides a `LavalinkApiResolutionScope` which is used to specify a node to use when resolving tracks. You can use the `LavalinkApiResolutionScope` by passing the `ApiClient` parameter to set the node to the node which also should play the track. + +## Example + +```csharp + var player = await GetPlayerAsync(connectToVoiceChannel: true).ConfigureAwait(false); + +if (player is null) +{ + return; +} + +var resolutionScope = new LavalinkApiResolutionScope(player.ApiClient); + +var track = await _audioService.Tracks + .LoadTrackAsync(query, TrackSearchMode.YouTube, resolutionScope) + .ConfigureAwait(false); + +if (track is null) +{ + await FollowupAsync("😖 No results.").ConfigureAwait(false); + return; +} + +var position = await player.PlayAsync(track).ConfigureAwait(false); + +if (position is 0) +{ + await FollowupAsync($"🔈 Playing: {track.Uri}").ConfigureAwait(false); +} +else +{ + await FollowupAsync($"🔈 Added to queue: {track.Uri}").ConfigureAwait(false); +} +``` + +You can see that we are passing the `ApiClient` to the `LoadTrackAsync` method. This will make sure that the track is resolved by the node which also should play the track.